yesilcam-studios 0.1.0 → 0.3.0

package/src/files.js

@@ -0,0 +1,87 @@
+// Dosya yükleme / indirme. Küçük dosyalar base64 (aistudio-upload-asset, ≤14 MB), büyükler imzalı PUT (ys-upload-init → PUT → ys-upload-complete).
+// Kullanıcı medyası özeldir: indirme bağlantıları süreli imzalıdır; süresi geçmişse ys-media-resign ile yenilenir.
+import { readFileSync, writeFileSync, statSync, mkdirSync, existsSync } from 'node:fs'
+import { basename, extname, dirname, join, resolve } from 'node:path'
+import { ApiError } from './client.js'
+
+export const MIME = {
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.heic': 'image/heic',
+  '.mp4': 'video/mp4', '.mov': 'video/quicktime', '.webm': 'video/webm',
+  '.mp3': 'audio/mpeg', '.wav': 'audio/wav', '.m4a': 'audio/mp4', '.ogg': 'audio/ogg',
+  '.json': 'application/json', '.dxf': 'application/dxf', '.svg': 'image/svg+xml', '.pdf': 'application/pdf',
+}
+export const mimeOf = (p) => MIME[extname(String(p)).toLowerCase()] || 'application/octet-stream'
+export const kindOf = (mime) => (mime.startsWith('video') ? 'video' : mime.startsWith('audio') ? 'audio' : 'image')
+const BASE64_MAX = 14 * 1024 * 1024
+
+export function readLocal(path) {
+  const p = resolve(String(path))
+  if (!existsSync(p)) throw new ApiError('file_not_found', { path: p })
+  return { path: p, buf: readFileSync(p), size: statSync(p).size, mime: mimeOf(p), name: basename(p) }
+}
+
+export async function putPresigned(url, headers, buf, fetchImpl = globalThis.fetch) {
+  const r = await fetchImpl(url, { method: 'PUT', headers: headers || {}, body: buf })
+  if (!r.ok) throw new ApiError('upload_failed', { status: r.status })
+}
+
+/** Yerel dosya → kütüphane varlığı. → { asset_id, url, kind, thumb_url?, duration? } */
+export async function uploadAsset(c, path, { kind, label } = {}, fetchImpl) {
+  const f = readLocal(path)
+  const k = kind || kindOf(f.mime)
+  if (f.size <= BASE64_MAX && /^(image|video|audio)\//.test(f.mime) && f.mime !== 'image/heic') {
+    const r = await c.call('aistudio-upload-asset', { file_base64: `data:${f.mime};base64,${f.buf.toString('base64')}`, kind: k, label: (label || f.name).slice(0, 80) })
+    return { asset_id: String(r.asset_id ?? r.id), url: r.spaces_url || r.url || null, kind: r.kind || k }
+  }
+  const init = await c.call('ys-upload-init', { kind: k, mime: f.mime, size: f.size, name: f.name })
+  await putPresigned(init.url, init.headers || { 'Content-Type': f.mime }, f.buf, fetchImpl)
+  const done = await c.call('ys-upload-complete', { key: init.key, kind: k, label: (label || f.name).slice(0, 80) })
+  return { asset_id: String(done.asset_id), url: done.url || null, kind: done.kind || k, thumb_url: done.thumb_url || null, duration: done.duration_sec ?? null }
+}
+
+/** AI Influencer: kendi fotoğrafı (özel nesne) + açık onay + güvenlik denetimi. → { media_id, status, reason } */
+export async function uploadInfluencerPhoto(c, path, consent, fetchImpl) {
+  if (!consent) throw new ApiError('consent_required')
+  const f = readLocal(path)
+  if (!/^image\/(jpeg|png|webp)$/.test(f.mime)) throw new ApiError('unsupported_type', { mime: f.mime })
+  const init = await c.call('ys-influencer-photo-init', { mime: f.mime, size: f.size })
+  await putPresigned(init.url, init.headers || { 'Content-Type': f.mime }, f.buf, fetchImpl)
+  return c.call('ys-influencer-photo-check', { key: init.key, consent: 1 })
+}
+
+/** AI Influencer: kendi videosu (3–30 sn) → yükle + onay + denetim. → { asset_id, check } */
+export async function uploadInfluencerVideo(c, path, consent, fetchImpl) {
+  if (!consent) throw new ApiError('consent_required')
+  const up = await uploadAsset(c, path, { kind: 'video' }, fetchImpl)
+  const check = await c.call('ys-influencer-video-check', { asset_id: Number(up.asset_id), consent: 1 })
+  return { asset_id: up.asset_id, check }
+}
+
+/** Ses örneği (ses klonu): presigned PUT. → key */
+export async function uploadVoiceSample(c, path, fetchImpl) {
+  const f = readLocal(path)
+  const init = await c.call('ys-influencer-voice-sample-init', { filename: f.name, size: f.size })
+  await putPresigned(init.put_url, { 'Content-Type': init.content_type || f.mime }, f.buf, fetchImpl)
+  return init.key
+}
+
+const fileNameFromUrl = (url, fallback = 'download') => {
+  try { const b = basename(new URL(url).pathname); return b && b.includes('.') ? decodeURIComponent(b) : fallback } catch { return fallback }
+}
+
+/** URL → dosya. `out` bir dizinse adı URL'den alınır. 403/400 (süresi dolmuş imza) → ys-media-resign ile bir kez yenilenir. */
+export async function downloadUrl(c, url, out, fetchImpl = globalThis.fetch) {
+  if (!url) throw new ApiError('nothing_to_download')
+  let target = resolve(String(out || fileNameFromUrl(url)))
+  if (existsSync(target) && statSync(target).isDirectory()) target = join(target, fileNameFromUrl(url))
+  let res = await fetchImpl(url)
+  if ((res.status === 403 || res.status === 400) && c) {
+    const r = await c.call('ys-media-resign', { urls: [url] }).catch(() => null)
+    const fresh = r?.urls?.[0]
+    if (fresh) res = await fetchImpl(fresh)
+  }
+  if (!res.ok) throw new ApiError('download_failed', { status: res.status })
+  mkdirSync(dirname(target), { recursive: true })
+  writeFileSync(target, Buffer.from(await res.arrayBuffer()))
+  return target
+}

package/src/mcp.js

@@ -1,64 +1,102 @@
-// Claude için MCP sunucusu (stdio). Araçlar CLI ile aynı istemciyi kullanır.
+// Claude (ve diğer MCP istemcileri) için stdio MCP sunucusu. Araçlar işlem kataloğundan türetilir (CLI ile birebir).
+// Jeton harcayan araçlar confirm=true olmadan YALNIZ teklif döner; istemci kullanıcı onayı olmadan jeton harcayamaz.
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod'
-import { readFileSync } from 'node:fs'
-import { basename, extname } from 'node:path'
-import { makeClient } from './client.js'
-import { getUserToken } from './config.js'
-import { imageJob, videoJob, tryonJob, waitForJob, describeJob, TIERS, ASPECTS } from './jobs.js'
-import { analyzePlanText } from './maket/analyze.js'
-import { SITE_URL } from './constants.js'
+import { makeClient, friendlyError, ApiError } from './client.js'
+import { getCredentials } from './config.js'
+import { selectOps, STUDIOS } from './registry.js'
+import { execute } from './run.js'
+import { VERSION, KEYS_URL } from './constants.js'
 
 const text = (data) => ({ content: [{ type: 'text', text: typeof data === 'string' ? data : JSON.stringify(data, null, 2) }] })
-const fail = (e) => ({ isError: true, content: [{ type: 'text', text: `Error: ${e?.message || e}` }] })
-const MIME = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.mp4': 'video/mp4', '.mp3': 'audio/mpeg', '.wav': 'audio/wav' }
+const fail = (e) => ({ isError: true, content: [{ type: 'text', text: `Error: ${friendlyError(e)}` }] })
 
-export function createServer({ client: injected } = {}) {
-  const server = new McpServer({ name: 'yesilcam', version: '0.1.0' })
-  const client = () => injected || makeClient(getUserToken())
-  const guarded = (fn) => async (args) => { try { return await fn(args) } catch (e) { return fail(e) } }
+export const INSTRUCTIONS = `Yeşilçam Studios tools: AI film, image, animation, design, website, fashion try-on, Maket and AI Influencer studios on the user's own account and token wallet.
+Rules:
+- Tools that spend tokens return a QUOTE first and charge nothing. Show the price to the user and only after they agree call the same tool again with the same arguments plus confirm=true. Never set confirm=true on your own. Use max_tokens as a safety limit.
+- Long jobs: pass wait=true (and save_to to download), or call yesilcam_wait with the returned kind and id. Progress is reported while waiting.
+- Media is private; links are signed and expire after a few hours (yesilcam_download refreshes them). Sharing publicly goes through yesilcam_share (may need approval).
+- Characters, influencers and people must be adults; real public figures are not allowed.
+- Account, payment, API key and social-account connection settings are only in the web app (https://yesilcamstudios.com/app).`
 
-  server.registerTool('yesilcam_balance', { description: 'Token balance of the signed-in Yeşilçam Studios account.', inputSchema: {} },
-    guarded(async () => text(await client().balance())))
-  server.registerTool('yesilcam_account', { description: 'Account name, email and subscription plan.', inputSchema: {} },
-    guarded(async () => text(await client().me())))
-  server.registerTool('yesilcam_pricing', { description: 'Production costs in tokens (Film Studio and Fashion Try-On operations) and token packs with prices.', inputSchema: {} },
-    guarded(async () => { const c = client(); const [ops, packs] = await Promise.all([c.modulePricing(), c.tokenPackages()]); return text({ operations: ops.filter((r) => ['ai-studio', 'fashion-tryon'].includes(r.module_key)).map((r) => ({ module: r.module_key, operation: r.operation_key, tokens: Number(r.base_cost_tokens), free_per_month: Number(r.monthly_free_limit || 0) })), packs }) }))
-  server.registerTool('yesilcam_list_assets', { description: 'List images/videos in the user library. Returns asset ids and URLs.', inputSchema: { kind: z.enum(['image', 'video']).optional(), limit: z.number().int().min(1).max(100).optional() } },
-    guarded(async ({ kind, limit }) => text(await client().assets({ kind, limit: limit || 40 }))))
-  server.registerTool('yesilcam_upload_asset', { description: 'Upload a local image/video/audio file to the library. Returns the asset id to use in other tools.', inputSchema: { path: z.string(), label: z.string().optional() } },
-    guarded(async ({ path, label }) => { const ext = extname(path).toLowerCase(); const mime = MIME[ext] || 'application/octet-stream'; const kind = mime.startsWith('video') ? 'video' : mime.startsWith('audio') ? 'audio' : 'image'; return text(await client().uploadAsset(`data:${mime};base64,${readFileSync(path).toString('base64')}`, kind, label || basename(path))) }))
-  server.registerTool('yesilcam_create_image', { description: 'Generate an image from a prompt (Film Studio). Costs tokens. Set wait=true to block until the result URL is ready.', inputSchema: { prompt: z.string().min(3), tier: z.enum(TIERS).optional(), aspect: z.enum(ASPECTS).optional(), framing: z.enum(['waist_up', 'waist_down', 'full_body']).optional(), wait: z.boolean().optional() } },
-    guarded(async ({ prompt, tier, aspect, framing, wait }) => run(client(), imageJob({ prompt, tier: tier || 'draft', aspect: aspect || '16:9', framing }), wait)))
-  server.registerTool('yesilcam_create_video', { description: 'Generate a video from a prompt (text2video) or animate an image asset (image2video, give source_asset_id). Costs tokens.', inputSchema: { prompt: z.string().optional(), source_asset_id: z.string().optional(), tier: z.enum(TIERS).optional(), aspect: z.enum(ASPECTS).optional(), duration: z.number().int().optional(), resolution: z.enum(['480p', '720p', '1080p']).optional(), generate_audio: z.boolean().optional(), wait: z.boolean().optional() } },
-    guarded(async (a) => run(client(), videoJob({ prompt: a.prompt || '', tier: a.tier || 'draft', aspect: a.aspect || '16:9', sourceAssetId: a.source_asset_id, duration: a.duration, resolution: a.resolution, generateAudio: a.generate_audio }), a.wait)))
-  server.registerTool('yesilcam_tryon', { description: 'Fashion Try-On: put a garment (image asset) on a person (image asset) or a saved character. Costs tokens.', inputSchema: { garment_asset_id: z.string(), person_asset_id: z.string().optional(), character_id: z.string().optional(), prompt: z.string().optional(), wait: z.boolean().optional() } },
-    guarded(async (a) => { if (!a.person_asset_id && !a.character_id) throw new Error('person_asset_id or character_id is required'); return run(client(), tryonJob({ garmentAssetId: a.garment_asset_id, personAssetId: a.person_asset_id, characterId: a.character_id, prompt: a.prompt }), a.wait) }))
-  server.registerTool('yesilcam_job_status', { description: 'Status and result URL of a generation job.', inputSchema: { job_id: z.string(), wait: z.boolean().optional() } },
-    guarded(async ({ job_id, wait }) => { const c = client(); const job = wait ? await waitForJob(c, job_id) : (await c.jobStatus(Number(job_id))).job; return text(describeJob(job)) }))
-  server.registerTool('yesilcam_list_jobs', { description: 'Recent generation jobs.', inputSchema: { limit: z.number().int().min(1).max(100).optional() } },
-    guarded(async ({ limit }) => text(await client().jobs({ limit: limit || 20 }))))
-  server.registerTool('yesilcam_list_characters', { description: 'Saved characters (for consistent faces across scenes).', inputSchema: {} },
-    guarded(async () => text(await client().characters())))
-  server.registerTool('yesilcam_maket_analyze', { description: 'Analyze a local DXF or JSON floor plan (Maket): walls, doors, windows, rooms, areas, layer roles. Free, runs locally.', inputSchema: { path: z.string() } },
-    guarded(async ({ path }) => text(analyzePlanText(readFileSync(path, 'utf8'), basename(path)))))
-  server.registerTool('yesilcam_maket_projects', { description: 'Saved Maket projects of the account.', inputSchema: {} },
-    guarded(async () => text(await client().maketList())))
-  server.registerTool('yesilcam_maket_save', { description: `Save a local floor plan as a Maket project; open it at ${SITE_URL}/app/maket.`, inputSchema: { path: z.string(), title: z.string().optional() } },
-    guarded(async ({ path, title }) => { const t = readFileSync(path, 'utf8'); const a = analyzePlanText(t, basename(path)); return text(await client().maketCreate({ title: title || basename(path, extname(path)), source_kind: a.source_kind, source_text: t, settings: { overrides: {}, wallHeight: 2.9 }, stats: a.stats })) }))
+export function buildToolSchema(op) {
+  const s = { ...op.input }
+  if (op.kind === 'spend') {
+    s.confirm = z.boolean().optional().describe('Set true ONLY after the user approved the quoted cost. Without it nothing is charged and a quote is returned.')
+    s.max_tokens = z.number().int().min(0).optional().describe('Refuse if the quote is above this many tokens')
+  }
+  if (op.wait) {
+    s.wait = z.boolean().optional().describe('Wait for the result (reports progress)')
+    s.max_wait_seconds = z.number().int().min(5).max(3600).optional().describe('How long to wait (default 900)')
+    s.save_to = z.string().optional().describe('Local file or folder to save the result to (implies wait)')
+  }
+  return s
+}
+
+export function toolDescription(op) {
+  const tag = op.kind === 'spend' ? (op.confirm ? ' [Needs confirm=true after the user approves.]' : ' [Spends tokens: returns a quote first; call again with confirm=true after the user approves.]') : op.kind === 'local' ? ' [Free, runs locally.]' : ''
+  return `${op.description}${tag}`
+}
+
+export function createServer({ client: injected, studios, readOnly } = {}) {
+  const server = new McpServer({ name: 'yesilcam', version: VERSION }, { instructions: INSTRUCTIONS })
+  let cached = null
+  const client = () => {
+    if (injected) return injected
+    if (cached) return cached
+    const cred = getCredentials()
+    if (!cred) throw new ApiError('not_logged_in')
+    cached = makeClient(cred)
+    return cached
+  }
+  for (const op of selectOps({ studios, readOnly })) {
+    server.registerTool(`yesilcam_${op.name}`, {
+      title: op.summary,
+      description: toolDescription(op),
+      inputSchema: buildToolSchema(op),
+      annotations: { title: op.summary, readOnlyHint: op.kind === 'read' || op.kind === 'local', destructiveHint: Boolean(op.destructive), idempotentHint: op.kind === 'read' || op.kind === 'local', openWorldHint: op.kind !== 'local' },
+    }, async (args, extra) => {
+      try {
+        const token = extra?._meta?.progressToken
+        let tick = 0
+        const onProgress = token != null && extra?.sendNotification ? (st) => {
+          tick += 1
+          const pct = st?.progress != null ? Math.max(0, Math.min(100, Number(st.progress))) : null
+          extra.sendNotification({ method: 'notifications/progress', params: { progressToken: token, progress: pct ?? tick, ...(pct != null ? { total: 100 } : {}), message: [st?.status, st?.stage].filter(Boolean).join(' · ') } }).catch(() => {})
+        } : undefined
+        const r = await execute(op, op.kind === 'local' ? null : client(), args, { confirmed: args?.confirm === true, onProgress })
+        if (r.status === 'quote') return text({ status: 'quote_only_nothing_charged', quote: r.quote, next: `Show this price to the user. If they approve, call yesilcam_${op.name} again with the same arguments and confirm=true.` })
+        if (r.status !== 'done') return text(r)
+        return text({ ...(r.quote ? { quoted_tokens: r.quote.total } : {}), result: r.result, ...(r.final ? { final: r.final } : {}), ...(r.track ? { track: `yesilcam_wait kind=${r.track.kind} id=${r.track.id}` } : {}) })
+      } catch (e) { return fail(e) }
+    })
+  }
   return server
 }
 
-async function run(c, payload, wait) {
-  const r = await c.createJob(payload)
-  const jobId = r?.job_id || r?.id || r?.job?.id
-  if (!jobId) return text(r)
-  if (!wait) return text({ job_id: String(jobId), status: 'queued', hint: 'Call yesilcam_job_status with wait=true to get the result.' })
-  return text(describeJob(await waitForJob(c, jobId)))
+export function parseArgs(argv) {
+  const o = { studios: [], readOnly: false }
+  for (let i = 0; i < argv.length; i++) {
+    const v = argv[i]
+    if (v === '--read-only') o.readOnly = true
+    else if (v === '--studios' && argv[i + 1]) o.studios = argv[++i].split(',').map((s) => s.trim()).filter(Boolean)
+    else if (v.startsWith('--studios=')) o.studios = v.slice(10).split(',').map((s) => s.trim()).filter(Boolean)
+    else if (v === '--help' || v === '-h') o.help = true
+    else if (v === '--version' || v === '-v') o.version = true
+  }
+  if (process.env.YESILCAM_MCP_STUDIOS && !o.studios.length) o.studios = process.env.YESILCAM_MCP_STUDIOS.split(',').map((s) => s.trim()).filter(Boolean)
+  if (process.env.YESILCAM_MCP_READ_ONLY === '1') o.readOnly = true
+  const bad = o.studios.filter((s) => !STUDIOS.includes(s))
+  if (bad.length) throw new Error(`unknown studio: ${bad.join(', ')} (use: ${STUDIOS.filter((s) => s !== 'core').join(', ')})`)
+  return o
 }
 
-export async function startStdio() {
-  const server = createServer()
+export async function startStdio(argv = process.argv.slice(2)) {
+  const o = parseArgs(argv)
+  if (o.version) { process.stdout.write(`${VERSION}\n`); return }
+  if (o.help) { process.stdout.write(`yesilcam-mcp ${VERSION}: Yeşilçam Studios MCP server (stdio).\nOptions: --studios image,film,animation,cinema,design,website,fashion,maket,influencer  --read-only\nSign in first with: yesilcam login  (API key from ${KEYS_URL})\n`); return }
+  if (!getCredentials()) process.stderr.write(`yesilcam-mcp: not signed in. Run "yesilcam login" (API key from ${KEYS_URL}) or set YESILCAM_API_KEY.\n`)
+  const server = createServer(o)
   await server.connect(new StdioServerTransport())
 }

package/src/ops/_util.js

@@ -0,0 +1,43 @@
+// İşlem kataloğu yardımcıları. Her işlem:
+// { name, group, action, summary, description, kind: 'read'|'write'|'spend'|'local', destructive?, input:{zod},
+//   positional?: alan adı (CLI ilk argüman), quote?(c,a) (spend), run(c,a,ctx), wait?: (sonuç, a) => { kind, id } }
+// kind=spend: MCP'de confirm=true olmadan yalnız teklif döner (jeton harcanmaz); CLI'da --yes ya da etkileşimli onay.
+import { z } from 'zod'
+
+export { z }
+export const ID = (d) => z.union([z.string(), z.number()]).describe(d)
+export const IDS = (d, max = 10) => z.array(z.union([z.string(), z.number()])).max(max).describe(d)
+export const NEG = z.string().max(500).optional().describe('Things to avoid (negative prompt), up to 500 characters')
+export const ASPECT3 = z.enum(['16:9', '9:16', '1:1'])
+export const n = (v) => (v == null || v === '' ? undefined : Number(v))
+export const ints = (arr) => (Array.isArray(arr) ? arr.map((x) => Number(x)).filter((x) => Number.isFinite(x)) : undefined)
+export const clean = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined && v !== null && v !== ''))
+
+export const op = (o) => o
+
+/** Tek işlem anahtarının bu plandaki bedeli (ai-studio modülü). */
+export async function opCost(c, key) {
+  const r = await c.call('aistudio-operation-cost', { operation_key: key })
+  // Ücretli planda aylık ücretsiz hakkı kalan işlemler 0'a düşer (sunucu da ücret almaz)
+  const free = Number(r?.monthlyFreeRemaining || 0) > 0 || Number(r?.dailyFreeRemaining || 0) > 0 || r?.isFreeForAll === true
+  return { key: free ? `${key} (free monthly use, ${r.monthlyFreeRemaining ?? r.dailyFreeRemaining ?? ''} left)` : key, tokens: free ? 0 : Number(r?.effectiveCost ?? r?.effective_cost ?? 0), balance: r?.currentBalance != null ? Number(r.currentBalance) : null }
+}
+/** Başka modüller için (fashion-tryon, maket …). */
+export async function moduleCost(c, moduleKey, operationKey) {
+  const r = await c.call('check-module-cost', { moduleKey, operationKey })
+  return { key: operationKey, tokens: Number(r?.effectiveCost ?? 0) }
+}
+export async function balanceOf(c) {
+  const r = await c.call('get-token-balance').catch(() => null)
+  return r && r.balance != null ? Number(r.balance) : null
+}
+/** Teklif nesnesi: { total, items:[{item, tokens}], balance, can_afford, notes? } */
+export async function quote(c, items, { balance, notes, approximate } = {}) {
+  const list = items.filter(Boolean).map((i) => ({ item: i.item, tokens: Math.ceil(Number(i.tokens) || 0) }))
+  const total = list.reduce((s, i) => s + i.tokens, 0)
+  const bal = balance != null ? Number(balance) : await balanceOf(c)
+  return clean({ total, items: list, balance: bal, can_afford: bal == null ? undefined : bal >= total, approximate: approximate || undefined, notes })
+}
+
+/** CLI/MCP'de dosya yolu gibi davranan alanlar (CLI ~ genişletmesi vb. için işaret). */
+export const PATH = (d) => z.string().min(1).describe(d)

package/src/ops/account.js

@@ -0,0 +1,62 @@
+import { z, op, n, clean } from './_util.js'
+import { checkOnce, waitFor, WAIT_KINDS, waitKindHelp } from '../wait.js'
+import { downloadUrl } from '../files.js'
+
+export default [
+  op({ name: 'account', group: 'account', action: 'show', kind: 'read', summary: 'Account, plan and token balance',
+    description: 'Shows the signed-in Yeşilçam Studios account: name, email, plan (Free, Basic, Pro), plan expiry, token balance and, when signed in with an API key, the key scopes.',
+    input: {},
+    run: async (c) => {
+      const [sub, bal, bill, ses] = await Promise.all([c.call('get-user-subscription-infos').catch(() => ({})), c.call('get-token-balance').catch(() => ({})), c.call('ys-billing-info').catch(() => null), c.session().catch(() => null)])
+      const plan = sub?.subscriptionPackageType || 'social-hive'
+      const label = { 'social-hive': 'Free', basic: 'Basic', professional: 'Pro' }
+      return clean({ name: [sub?.name, sub?.lastname].filter(Boolean).join(' ') || ses?.user?.name, email: sub?.email || ses?.user?.email, plan: label[bill?.effective_plan || plan] || plan,
+        plan_expires: (() => { const t = Number(sub?.subscriptionExpiredDate || bill?.expires_at); return t > 1e9 ? new Date(t * 1000).toISOString().slice(0, 10) : undefined })(), balance: bal?.balance != null ? Number(bal.balance) : undefined,
+        auth: c.kind, api_key: ses?.key ? { name: ses.key.name, prefix: ses.key.prefix, scopes: ses.scopes } : undefined })
+    } }),
+  op({ name: 'balance', group: 'account', action: 'balance', kind: 'read', summary: 'Token balance',
+    description: 'Current token balance of the account.', input: {},
+    run: async (c) => { const r = await c.call('get-token-balance'); return { balance: Number(r.balance) } } }),
+  op({ name: 'pricing', group: 'account', action: 'pricing', kind: 'read', summary: 'Token prices of every operation and token packs',
+    description: 'Lists base token prices per operation for all studios (your plan may apply a multiplier: Pro x0.8, Free x1.3; use the price tool for your exact price) and the token packs you can buy.',
+    input: { search: z.string().optional().describe('Filter operations by text, e.g. "video" or "inf_"') },
+    run: async (c, a) => {
+      const [ops, packs] = await Promise.all([c.call('get-all-module-pricing'), c.call('get-token-packages', { app: 'yesilcam' }).catch(() => [])])
+      const rows = (Array.isArray(ops) ? ops : []).filter((r) => ['ai-studio', 'fashion-tryon', 'maket'].includes(r.module_key) && String(r.status ?? '1') === '1')
+        .map((r) => ({ module: r.module_key, operation: r.operation_key, tokens: Number(r.base_cost_tokens) }))
+        .filter((r) => !a.search || `${r.module} ${r.operation}`.toLowerCase().includes(String(a.search).toLowerCase())).sort((x, y) => x.tokens - y.tokens)
+      const pk = (Array.isArray(packs) ? packs : packs?.items || []).map((p) => clean({ id: p.id, title: p.title, tokens: Number(p.token_amount), bonus_percent: Number(p.bonus_percentage || 0), usd: n(p.price_usd), usd_without_plan: n(p.price_usd_standard), try: n(p.price_tr), try_without_plan: n(p.price_tr_standard) }))
+      return { operations: rows, packs: pk, note: 'Base prices. Your plan multiplier applies (Pro x0.8, Basic x1.0, Free x1.3). Failed jobs are refunded.' }
+    } }),
+  op({ name: 'price', group: 'account', action: 'price', kind: 'read', summary: 'Exact token price of one operation for your plan',
+    description: 'Exact token price of one operation key for the signed-in plan (keys come from the pricing tool, e.g. image_standard, video_draft_5s, inf_talk_veo_sec).',
+    input: { operation: z.string().min(2).describe('Operation key, e.g. image_standard'), module: z.enum(['ai-studio', 'fashion-tryon', 'maket']).optional().describe('Module (default ai-studio)') },
+    positional: 'operation',
+    run: async (c, a) => { const r = await c.call('check-module-cost', { moduleKey: a.module || 'ai-studio', operationKey: a.operation }); return clean({ operation: a.operation, tokens: n(r.effectiveCost), base_tokens: n(r.baseCost), multiplier: n(r.multiplier), balance: n(r.currentBalance) }) } }),
+  op({ name: 'transactions', group: 'account', action: 'transactions', kind: 'read', summary: 'Recent token transactions',
+    description: 'Recent token transactions (charges, refunds, grants, purchases).',
+    input: { page: z.number().int().min(1).optional(), limit: z.number().int().min(1).max(100).optional() },
+    run: (c, a) => c.call('get-token-transactions', { page: a.page || 1, limit: a.limit || 20 }) }),
+
+  // ── ortak bekleme / durum / indirme
+  op({ name: 'status', group: 'wait', action: 'status', kind: 'read', summary: 'Status of any job or project',
+    description: `One status read of a running job or project. kind: ${waitKindHelp()}.`,
+    input: { kind: z.enum(WAIT_KINDS).describe('What to check'), id: z.union([z.string(), z.number()]).describe('Job / project id (renders: projectId:renderId)') },
+    positional: ['kind', 'id'],
+    run: (c, a) => checkOnce(c, a.kind, a.id) }),
+  op({ name: 'wait', group: 'wait', action: 'until', kind: 'read', summary: 'Wait until a job or project finishes (optionally download the result)',
+    description: `Polls a job or project until it finishes, needs your action, or max_wait_seconds passes; reports progress. Optionally saves the result file. kind: ${waitKindHelp()}.`,
+    input: { kind: z.enum(WAIT_KINDS), id: z.union([z.string(), z.number()]), max_wait_seconds: z.number().int().min(5).max(3600).optional().describe('Default 600'),
+      save_to: z.string().optional().describe('Local file or folder to save the result to') },
+    positional: ['kind', 'id'],
+    run: async (c, a, ctx) => {
+      const st = await waitFor(c, a.kind, a.id, { timeoutMs: (a.max_wait_seconds || 600) * 1000, onTick: ctx?.onProgress })
+      if (a.save_to && st.ok && st.url) st.saved = await downloadUrl(c, st.url, a.save_to)
+      return st
+    } }),
+  op({ name: 'download', group: 'library', action: 'download', kind: 'read', summary: 'Download a result or library file',
+    description: 'Downloads a file from a Yeşilçam Studios URL (private signed links are refreshed automatically) to a local path.',
+    input: { url: z.string().url().describe('File URL from a result or the library'), save_to: z.string().optional().describe('Local file or folder (default: current folder)') },
+    positional: 'url',
+    run: async (c, a) => ({ saved: await downloadUrl(c, a.url, a.save_to || '.') }) }),
+]

package/src/ops/animation.js

@@ -0,0 +1,126 @@
+// Animation Studio: 25 tarz (tek motor ailesi aistudio-anim-*), Inkmation (aistudio-inkmation-*), Custom (aistudio-motion-*).
+// Ink Landscape = engine "inkland" (palet + mevsim).
+import { z, op, ID, NEG, ASPECT3, n, clean, quote } from './_util.js'
+import { uploadAsset } from '../files.js'
+
+// Uygulama vitrinindeki ad + sunucu motoru (+ varyant). Ad çevrilmez.
+export const STYLES = [
+  ['foliomation', 'Foliomation'], ['papercraft', 'Papercraft'], ['dioramation', 'Dioramation'], ['typemation', 'Typemation'], ['fluxmation', 'Fluxmation'],
+  ['puppetmation', 'Puppetmation'], ['inkland', 'Ink Landscape'], ['popbook', 'Popbook (interactive book)'], ['labmation', 'Labmation (interactive lab)'],
+  ['wuxiamation-legend2d', 'Wuxiamation · Legend 2D'], ['wuxiamation-cinematic3d', 'Wuxiamation · Cinematic 3D'], ['celmation', 'Celmation'], ['neonmation', 'Neonmation'],
+  ['toymation', 'Toymation'], ['toonmation', 'Toonmation'], ['shadowmation', 'Shadowmation'], ['pixelmation', 'Pixelmation'], ['panelmation', 'Panelmation'],
+  ['claymation', 'Claymation'], ['knitmation', 'Knitmation'], ['sumimation', 'Sumimation'], ['postermation', 'Postermation'], ['epicmation', 'Epicmation'],
+]
+const STYLE_IDS = STYLES.map((s) => s[0])
+const MOTION = ['wuxiamation', 'celmation', 'neonmation', 'toymation', 'toonmation', 'pixelmation', 'panelmation', 'claymation', 'knitmation', 'sumimation', 'postermation', 'epicmation']
+const engineOf = (style) => { const [e, v] = String(style).split('-'); return { engine: e, variant: v } }
+
+const animInput = {
+  style: z.enum(STYLE_IDS).describe('Animation style (see yesilcam_animation_styles)'),
+  prompt: z.string().min(12).max(8000).describe('What the film is about (story, topic or script)'),
+  title: z.string().max(200).optional(),
+  lang: z.enum(['tr', 'en', 'de', 'fr', 'es', 'it']).optional().describe('Narration language'),
+  aspect: ASPECT3.optional(), seconds: z.number().int().min(10).max(120).optional().describe('Target length (default 30)'),
+  voice: z.string().optional().describe('Voice id (yesilcam_animation_voices); empty = automatic'),
+  music: z.string().max(120).optional().describe('auto, none, or a music description'),
+  captions: z.enum(['bottom', 'top', 'none']).optional(), narrate: z.boolean().optional(),
+  palette: z.string().optional().describe('postermation: auto|bosphorus|riviera|noir|pastel · inkland: auto|ink|sepia|qinglu|night|yesilcam'),
+  season: z.enum(['auto', 'spring', 'summer', 'autumn', 'winter']).optional().describe('Ink Landscape only'),
+  note: z.string().max(300).optional().describe('Extra style note'),
+  negative_prompt: NEG,
+}
+const animOptions = (a) => { const { variant } = engineOf(a.style); return clean({ lang: a.lang, aspect: a.aspect, maxSeconds: a.seconds, voice: a.voice, music: a.music, captions: a.captions, narrate: a.narrate, palette: a.palette, season: a.season, style: a.note, variant, negative_prompt: a.negative_prompt }) }
+const TIERS = z.enum(['premium', 'professional', 'cinema'])
+
+const renderInput = { project_id: ID('Animation project id'), format: z.enum(['mp4', 'webp', 'gif']).optional(), quality: z.enum(['hd', '4k']).optional().describe('mp4 only'), aspect: ASPECT3.optional() }
+const renderBody = (a) => clean({ project_id: Number(a.project_id), format: a.format || 'mp4', quality: (a.format || 'mp4') === 'mp4' ? (a.quality || 'hd') : undefined, aspect: a.aspect })
+
+export default [
+  op({ name: 'animation_styles', group: 'animation', action: 'styles', kind: 'local', summary: 'The 25 animation styles',
+    description: 'Lists Animation Studio styles: 23 engine styles (including Ink Landscape and two Wuxiamation variants), plus Inkmation (yesilcam_inkmation_create) and Custom (yesilcam_custom_animation_create). "cinema" tier is available for moving styles on Basic/Pro.',
+    input: {},
+    run: () => ({ styles: STYLES.map(([id, name]) => ({ id, name, cinema_tier: MOTION.includes(engineOf(id).engine), interactive: ['popbook', 'labmation'].includes(id) || undefined })), also: [{ id: 'inkmation', name: 'Inkmation', tool: 'inkmation_create' }, { id: 'custom', name: 'Custom', tool: 'custom_animation_create' }] }) }),
+  op({ name: 'animation_voices', group: 'animation', action: 'voices', kind: 'read', summary: 'Narration voices for Animation and Inkmation',
+    description: 'Voices for Animation Studio and Inkmation narration (id, name, language, gender, preview).', input: {},
+    run: (c) => c.call('aistudio-inkmation-voices') }),
+  op({ name: 'animation_create', group: 'animation', action: 'create', kind: 'spend', summary: 'Animation Studio: make an animated film in one of 25 styles',
+    description: 'Creates an animated film in a chosen style: the director writes scenes, images, narration and music are made, then you render MP4/WebP/GIF (yesilcam_animation_render). Tiers: premium (best story craft), professional (fast, economical), cinema (moving styles, Basic/Pro). The estimate is charged up front and unused tokens are refunded at the end.',
+    positional: 'prompt',
+    input: { ...animInput, tier: TIERS.optional().describe('premium (default), professional, cinema') },
+    quote: async (c, a) => { const { engine } = engineOf(a.style); const r = await c.call('aistudio-anim-quote', { engine, prompt: a.prompt, options: animOptions(a) })
+      const t = r.tiers?.[a.tier || 'premium']; if (!t) throw new Error(`tier ${a.tier} is not available for ${a.style}`)
+      return quote(c, Object.entries(t.parts || { total: t.tokens }).map(([k, v]) => ({ item: k, tokens: v })), { balance: n(r.balance), notes: 'Estimate charged up front; unused tokens are refunded. Rendering is a separate small charge.' }) },
+    run: async (c, a) => { const { engine } = engineOf(a.style); return c.call('aistudio-anim-create', clean({ engine, tier: a.tier || 'premium', prompt: a.prompt, title: a.title, options: animOptions(a) })) },
+    wait: (r) => ({ kind: 'anim', id: r.project_id }) }),
+  op({ name: 'animation_story', group: 'animation', action: 'story', kind: 'spend', summary: 'Sam writes or improves an animation story',
+    description: 'Sam writes (mode=write) or improves (mode=improve) the story/prompt for an animation style or Inkmation. Charged by actual usage.',
+    input: { style: z.enum([...STYLE_IDS, 'inkmation']), text: z.string().max(6000), mode: z.enum(['write', 'improve']).optional(), lang: z.enum(['tr', 'en', 'de', 'fr', 'es', 'it']).optional(), seconds: z.number().int().min(10).max(300).optional() },
+    quote: async (c, a) => { const { engine } = engineOf(a.style); const r = await c.call('aistudio-anim-quote', { engine: engine === 'inkmation' ? 'foliomation' : engine, prompt: a.text || 'story', options: clean({ lang: a.lang, maxSeconds: a.seconds }) }).catch(() => ({}))
+      return quote(c, [{ item: 'assistant (estimate)', tokens: Number(r.assist || 0) }], { balance: n(r.balance), approximate: true }) },
+    run: (c, a) => { const { engine, variant } = engineOf(a.style); return c.call('aistudio-anim-story-assist', { engine, mode: a.mode || 'write', text: a.text || '', options: clean({ lang: a.lang, maxSeconds: a.seconds, variant }) }) } }),
+  op({ name: 'animation_list', group: 'animation', action: 'list', kind: 'read', summary: 'Your animation projects',
+    description: 'Animation Studio projects (newest first).', input: { style: z.string().optional() },
+    run: (c, a) => c.call('aistudio-anim-list', clean({ engine: a.style ? engineOf(a.style).engine : undefined })) }),
+  op({ name: 'animation_get', group: 'animation', action: 'get', kind: 'read', summary: 'An animation project with its renders',
+    description: 'Status, progress, scenes and renders of an animation project.', input: { project_id: ID('Project id') }, positional: 'project_id',
+    run: async (c, a) => { const r = await c.call('aistudio-anim-get', { project_id: Number(a.project_id) }); if (r?.spec) r.spec = { scenes: (r.spec.scenes || []).length }; return r } }),
+  op({ name: 'animation_render', group: 'animation', action: 'render', kind: 'spend', summary: 'Render an animation to MP4 (HD/4K), WebP or GIF',
+    description: 'Renders a ready animation project to a video file. Priced by render time (small); settled after rendering.',
+    input: renderInput, positional: 'project_id',
+    quote: async (c, a) => { const r = await c.call('aistudio-anim-render-quote', renderBody(a)); return quote(c, [{ item: `render ${r.format} ${r.quality || ''} ${r.duration || ''}s`, tokens: r.tokens }], { balance: n(r.balance) }) },
+    run: async (c, a) => { const r = await c.call('aistudio-anim-render', renderBody(a)); return { render_id: String(r.render_id), status: r.status, tokens_charged: n(r.tokens_charged), wait_id: `${a.project_id}:${r.render_id}` } },
+    wait: (r) => ({ kind: 'anim_render', id: r.wait_id }) }),
+  op({ name: 'animation_share', group: 'animation', action: 'share', kind: 'write', summary: 'Make an animation public (share link) or private',
+    description: 'Creates or removes a public share link for a ready animation project.', input: { project_id: ID('Project id'), public: z.boolean().optional().describe('default true') }, positional: 'project_id',
+    run: async (c, a) => { const r = await c.call('aistudio-anim-share', { project_id: Number(a.project_id), public: a.public !== false }); return { ...r, url: r.share_token ? `https://yesilcamstudios.com/app/p/${r.share_token}` : null } } }),
+
+  // ── Custom
+  op({ name: 'custom_animation_create', group: 'animation', action: 'custom', kind: 'spend', summary: 'Animation › Custom: animate your own image along a camera path',
+    description: 'Turns an image into a 5, 10 or 15 second video. Give a motion prompt and/or camera moves (each segment at least 3 s; segments must add up to the duration) and up to 3 objects to move. Tier draft (720p) or standard (1080p). Priced per second.',
+    input: { image_asset_id: ID('Image asset id').optional(), image_path: z.string().optional().describe('Local image (uploaded first)'), prompt: z.string().max(1500).optional(),
+      tier: z.enum(['draft', 'standard']).optional(), aspect: ASPECT3.optional(), duration: z.union([z.literal(5), z.literal(10), z.literal(15)]).optional(),
+      camera: z.array(z.object({ axis: z.enum(['pan', 'tilt', 'zoom', 'roll', 'horizontal', 'vertical']), value: z.number().min(-10).max(10), seconds: z.number().int().min(3) })).max(3).optional().describe('Guided camera segments'),
+      objects: z.array(z.object({ x0: z.number(), y0: z.number(), x1: z.number(), y1: z.number(), label: z.string().max(80) })).max(3).optional().describe('Objects to move (0..1 coordinates from start to end)'), negative_prompt: NEG },
+    prepare: (c, a) => {
+      const duration = a.duration || 5
+      if (a.camera?.length && a.camera.reduce((s, x) => s + x.seconds, 0) !== duration) throw new Error(`camera segment seconds must add up to ${duration}`)
+      if (!a.prompt && !a.camera?.length && !a.objects?.length) throw new Error('give a prompt, camera segments or objects')
+      if (!a.image_asset_id && !a.image_path) throw new Error('give image_asset_id or image_path')
+      return { duration, tier: a.tier || 'standard' }
+    },
+    quote: async (c, a, p) => { const r = await c.call('aistudio-motion-quote', { tier: p.tier, duration: p.duration }); return quote(c, [{ item: `${p.tier} ${p.duration}s`, tokens: r.price?.total }], { balance: n(r.balance) }) },
+    run: async (c, a, ctx, p) => {
+      const src = a.image_asset_id ? Number(a.image_asset_id) : Number((await uploadAsset(c, a.image_path, { kind: 'image' })).asset_id)
+      const camera = a.camera?.length ? { mode: 'guided', style: 'pan', segments: a.camera.map((s) => ({ axis: s.axis, value: s.value, seconds: s.seconds })) } : undefined
+      return c.call('aistudio-motion-create', clean({ source_asset_id: src, prompt: a.prompt, tier: p.tier, aspect: a.aspect, duration: p.duration, camera, objects: a.objects, negative_prompt: a.negative_prompt }))
+    },
+    wait: (r) => ({ kind: 'motion', id: r.job_id }) }),
+  op({ name: 'custom_animation_list', group: 'animation', action: 'custom-list', kind: 'read', summary: 'Your Custom animations',
+    description: 'Animation › Custom jobs with status and result video.', input: { limit: z.number().int().min(1).max(48).optional() },
+    run: (c, a) => c.call('aistudio-motion-list', { limit: a.limit || 24 }) }),
+
+  // ── Inkmation
+  op({ name: 'inkmation_create', group: 'inkmation', action: 'create', kind: 'spend', summary: 'Inkmation: brush-drawn explainer film from a story',
+    description: 'Inkmation draws your story with an animated brush, with narration and music in Turkish and/or English. Pick a platform (sets aspect and max length) and a drawing style. Tiers premium / professional. Then render with yesilcam_inkmation_render.',
+    positional: 'story',
+    input: { story: z.string().min(40).max(12000), title: z.string().max(200).optional(), tier: z.enum(['premium', 'professional']).optional(),
+      platform: z.enum(['youtube', 'youtube-shorts', 'instagram-reels', 'tiktok', 'story', 'instagram-post', 'instagram-portrait', 'facebook', 'x', 'linkedin', 'pinterest']).optional(),
+      languages: z.array(z.enum(['tr', 'en'])).min(1).max(2).optional(), seconds: z.number().int().min(15).max(300).optional(),
+      drawing: z.enum(['normal', 'anime', 'chinese', 'japanese', '3d', 'ink', 'watercolor', 'pastel', 'bw-ink', 'pencil', 'clean-bw']).optional(), tone: z.string().max(80).optional(),
+      music: z.string().max(80).optional().describe('auto or a music description'), voice_tr: z.string().optional(), voice_en: z.string().optional(), negative_prompt: NEG },
+    prepare: (c, a) => ({ options: clean({ languages: a.languages, platform: a.platform, maxSeconds: a.seconds, style: a.drawing, tone: a.tone, musicStyle: a.music, voices: clean({ tr: a.voice_tr, en: a.voice_en }), autoAudio: true, negative_prompt: a.negative_prompt }) }),
+    quote: async (c, a, p) => { const r = await c.call('aistudio-inkmation-quote', { story: a.story, options: p.options, cast: [] }); const t = r.tiers?.[a.tier || 'professional'] || {}
+      return quote(c, [{ item: 'script', tokens: t.script_tokens }, { item: 'voice and music', tokens: t.audio_tokens }], { balance: n(r.balance) }) },
+    run: (c, a, ctx, p) => c.call('aistudio-inkmation-create', clean({ title: a.title, story: a.story, tier: a.tier || 'professional', options: p.options, cast: [] })),
+    wait: (r) => ({ kind: 'inkmation', id: r.project_id }) }),
+  op({ name: 'inkmation_list', group: 'inkmation', action: 'list', kind: 'read', summary: 'Your Inkmation projects', description: 'Inkmation projects.', input: {},
+    run: (c) => c.call('aistudio-inkmation-list') }),
+  op({ name: 'inkmation_get', group: 'inkmation', action: 'get', kind: 'read', summary: 'An Inkmation project', description: 'Status, script, audio state and renders of an Inkmation project.',
+    input: { project_id: ID('Project id') }, positional: 'project_id', run: (c, a) => c.call('aistudio-inkmation-get', { project_id: Number(a.project_id) }) }),
+  op({ name: 'inkmation_render', group: 'inkmation', action: 'render', kind: 'spend', summary: 'Render an Inkmation film',
+    description: 'Renders a ready Inkmation project (MP4 HD/4K, WebP or GIF; optional language and drawing style switch at render time).',
+    input: { ...renderInput, project_id: ID('Inkmation project id'), lang: z.enum(['tr', 'en']).optional(), drawing: z.string().optional() }, positional: 'project_id',
+    quote: async (c, a) => { const r = await c.call('aistudio-inkmation-render-quote', clean({ ...renderBody(a), lang: a.lang, style: a.drawing })); return quote(c, [{ item: `render ${r.format} ${r.duration || ''}s`, tokens: r.tokens }], { balance: n(r.balance) }) },
+    run: async (c, a) => { const r = await c.call('aistudio-inkmation-render', clean({ ...renderBody(a), lang: a.lang, style: a.drawing })); return { render_id: String(r.render_id), status: r.status, tokens_charged: n(r.tokens_charged), wait_id: `${a.project_id}:${r.render_id}` } },
+    wait: (r) => ({ kind: 'inkmation_render', id: r.wait_id }) }),
+]

package/src/ops/cinema.js

@@ -0,0 +1,58 @@
+// Cinema Studio (video düzenleyici): proje listesi, dışa aktarma, seslendirme, konuşan sunucu, altyazı.
+import { z, op, ID, n, clean, opCost, quote } from './_util.js'
+import { uploadAsset } from '../files.js'
+
+const J = (v) => { if (v && typeof v === 'object') return v; try { return JSON.parse(v || '{}') } catch { return {} } }
+/** Zaman çizelgesinin sonu (sn, hız dahil) — sunucunun ücretlendirdiği süre. */
+export function timelineSeconds(data) {
+  let end = 0
+  for (const t of J(data).tracks || []) for (const it of t.items || []) {
+    const start = Number(it.start || 0)
+    let len = 0
+    if (it.dur != null) len = Number(it.dur)
+    else if (it.out != null) len = (Number(it.out) - Number(it.in || 0)) / (Number(it.speed) || 1)
+    else if (it.duration != null) len = Number(it.duration) / (Number(it.speed) || 1)
+    end = Math.max(end, start + Math.max(0, len))
+  }
+  return Math.ceil(end)
+}
+
+export default [
+  op({ name: 'cinema_projects', group: 'cinema', action: 'list', kind: 'read', summary: 'Cinema Studio projects',
+    description: 'Cinema Studio (video editor) projects with duration, aspect and last export link.', input: {},
+    run: (c) => c.call('aistudio-cinema-project-list') }),
+  op({ name: 'cinema_render', group: 'cinema', action: 'render', kind: 'spend', summary: 'Export a Cinema Studio project to a video file',
+    description: 'Exports a Cinema Studio timeline to MP4/MOV/WebM at 720p, 1080p or 4K (2160p). Priced per second of timeline at the chosen resolution.',
+    input: { project_id: ID('Cinema project id'), resolution: z.enum(['720p', '1080p', '2160p']).optional(), format: z.enum(['mp4', 'mov', 'webm']).optional(), fps: z.number().int().min(1).max(120).optional(),
+      preset: z.enum(['youtube', 'shorts', 'ig_square', 'ig_portrait', 'linkedin']).optional() },
+    positional: 'project_id',
+    prepare: async (c, a) => { const p = await c.call('aistudio-cinema-project-get', { project_id: a.project_id }); const s = timelineSeconds(p.data); if (!s) throw new Error('Empty timeline'); return { seconds: s, res: a.resolution || '1080p' } },
+    quote: async (c, a, p) => { const x = await opCost(c, `cinema_render_${p.res}`); return quote(c, [{ item: `cinema_render_${p.res} x ${p.seconds}s`, tokens: x.tokens * p.seconds }], { balance: x.balance }) },
+    run: (c, a, ctx, p) => c.call('aistudio-cinema-render', clean({ project_id: a.project_id, format: a.format || 'mp4', resolution: p.res, fps: a.fps || 30, preset: a.preset })),
+    wait: (r) => ({ kind: 'job', id: r.job_id }) }),
+  op({ name: 'cinema_voices', group: 'cinema', action: 'voices', kind: 'read', summary: 'Narration voices of Cinema Studio (house voices + your cloned voices)',
+    description: 'House voices and your own cloned voices for Cinema Studio narration and the talking presenter.', input: {},
+    run: (c) => c.call('aistudio-cinema-voices') }),
+  op({ name: 'cinema_narrate', group: 'cinema', action: 'narrate', kind: 'spend', summary: 'Text to narration audio (saved to the library)',
+    description: 'Turns text (up to 5,000 characters) into a narration audio file with word timings, in a house voice or your cloned voice. Priced per character (minimum 100 tokens).',
+    positional: 'text',
+    input: { text: z.string().min(1).max(5000), voice: z.string().describe('House voice key (warm_female, warm_male, energetic_female, energetic_male, calm_narrator, deep_trailer) or your v:<id>'), stability: z.union([z.literal(0), z.literal(0.5), z.literal(1)]).optional() },
+    quote: async (c, a) => { const r = await c.call('aistudio-cinema-ai-rates'); return quote(c, [{ item: `narration ${a.text.length} chars`, tokens: Math.max(Number(r.min_tokens || 100), Math.ceil(Number(r.per_char) * a.text.length)) }], { balance: n(r.balance) }) },
+    run: (c, a) => c.call('aistudio-cinema-narrate', clean({ text: a.text, voice: a.voice, stability: a.stability })) }),
+  op({ name: 'cinema_presenter', group: 'cinema', action: 'presenter', kind: 'spend', summary: 'Talking presenter: a photo of a person speaks your text or audio',
+    description: 'Makes a talking presenter video from a portrait image and an audio file (2-60 s) or text + voice. Tier standard or pro. Priced per second (plus narration when text is given).',
+    input: { image_asset_id: ID('Portrait image asset id').optional(), image_path: z.string().optional(), audio_asset_id: ID('Audio asset id').optional(), text: z.string().max(1000).optional(), voice: z.string().optional(), tier: z.enum(['standard', 'pro']).optional(), prompt: z.string().max(300).optional() },
+    prepare: (c, a) => { if (!a.image_asset_id && !a.image_path) throw new Error('give image_asset_id or image_path'); if (!a.audio_asset_id && !(a.text && a.voice)) throw new Error('give audio_asset_id, or text + voice'); return { tier: a.tier || 'standard' } },
+    quote: async (c, a, p) => { const r = await c.call('aistudio-cinema-ai-rates'); const sec = a.text ? Math.min(60, Math.max(2, Math.ceil(a.text.length / 14))) : 60
+      return quote(c, [{ item: `presenter ${p.tier} ~${sec}s`, tokens: Number(r.per_presenter_sec?.[p.tier] || 0) * sec }, a.text && { item: 'narration', tokens: Math.ceil(Number(r.per_char) * a.text.length) }], { balance: n(r.balance), approximate: true, notes: a.text ? 'Seconds estimated from text length.' : 'Upper bound (60 s); charged for the actual audio length.' }) },
+    run: async (c, a, ctx, p) => { const img = a.image_asset_id ? Number(a.image_asset_id) : Number((await uploadAsset(c, a.image_path, { kind: 'image' })).asset_id)
+      return c.call('aistudio-cinema-presenter', clean({ image_asset_id: img, audio_asset_id: n(a.audio_asset_id), text: a.audio_asset_id ? undefined : a.text, voice: a.audio_asset_id ? undefined : a.voice, tier: p.tier, prompt: a.prompt })) },
+    wait: (r) => ({ kind: 'cinema_ai', id: r.job_id }) }),
+  op({ name: 'cinema_subtitles', group: 'cinema', action: 'subtitles', kind: 'spend', summary: 'Automatic subtitles for a Cinema Studio timeline',
+    description: 'Transcribes the speech on a Cinema Studio timeline and adds subtitles. Priced per second of speech.',
+    input: { project_id: ID('Cinema project id'), language: z.string().max(3).optional().describe('2-3 letter code or auto') }, positional: 'project_id',
+    prepare: async (c, a) => { const p = await c.call('aistudio-cinema-project-get', { project_id: a.project_id }); return { seconds: timelineSeconds(p.data) } },
+    quote: async (c, a, p) => { const r = await c.call('aistudio-cinema-ai-rates'); return quote(c, [{ item: `subtitles ~${p.seconds}s`, tokens: Number(r.stt_base || 0) + Math.ceil(Number(r.per_stt_sec || 0) * p.seconds) }], { balance: n(r.balance), approximate: true }) },
+    run: (c, a) => c.call('aistudio-cinema-subtitles', { project_id: a.project_id, scope: 'timeline', language: a.language || 'auto' }),
+    wait: (r) => ({ kind: 'cinema_ai', id: r.job_id }) }),
+]