videobook 0.0.0-stage → 0.2.0

package/dist/provider-prompt-transform.js

@@ -0,0 +1,77 @@
+import { scanNotebookMentions } from "videobook-engine/notebook-mentions";
+import { PREVIEW_PLACEHOLDER_HOST } from "./preview-payload.js";
+// An @<artifact-id> token is the internal reference currency between the
+// grid resolver and the per-tool dialect rewrite; one surviving into a
+// provider payload means the rewrite missed it.
+const ARTIFACT_ID_MENTION_PATTERN = /@[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}(?![\w-])/giu;
+export class ProviderMentionError extends Error {
+    tokens;
+    toolName;
+    constructor(toolName, tokens) {
+        super(`Unresolved provider mention${tokens.length === 1 ? "" : "s"} `
+            + `${tokens.join(", ")} in ${toolName}`);
+        this.name = "ProviderMentionError";
+        this.tokens = tokens;
+        this.toolName = toolName;
+    }
+}
+class ProviderPlaceholderError extends Error {
+    paths;
+    toolName;
+    constructor(toolName, paths) {
+        super(`Preview placeholder URL reached wire payload for ${toolName}: ${paths.join(", ")}`);
+        this.name = "ProviderPlaceholderError";
+        this.paths = paths;
+        this.toolName = toolName;
+    }
+}
+export function unresolvedProviderMentions(prompt) {
+    const leaks = [
+        ...scanNotebookMentions(prompt).map((mention) => mention.raw),
+        ...[...prompt.matchAll(ARTIFACT_ID_MENTION_PATTERN)].map((match) => match[0]),
+    ];
+    return [...new Set(leaks)];
+}
+export function assertNoUnresolvedMentions(prompt, options) {
+    const tokens = unresolvedProviderMentions(prompt);
+    if (tokens.length > 0)
+        throw new ProviderMentionError(options.toolName, tokens);
+}
+function visitProviderPayload(value, path, key, leaks, placeholders) {
+    if (typeof value === "string") {
+        if (value.includes(PREVIEW_PLACEHOLDER_HOST))
+            placeholders.push(path);
+        if (key.toLowerCase().includes("prompt") || key === "text") {
+            for (const token of unresolvedProviderMentions(value)) {
+                leaks.push({ path, token });
+            }
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => {
+            visitProviderPayload(item, `${path}[${index}]`, key, leaks, placeholders);
+        });
+        return;
+    }
+    if (!value || typeof value !== "object")
+        return;
+    for (const [childKey, childValue] of Object.entries(value)) {
+        visitProviderPayload(childValue, path ? `${path}.${childKey}` : childKey, childKey, leaks, placeholders);
+    }
+}
+function inspectProviderPayload(value) {
+    const promptLeaks = [];
+    const placeholderPaths = [];
+    visitProviderPayload(value, "", "", promptLeaks, placeholderPaths);
+    return { promptLeaks, placeholderPaths };
+}
+export function assertProviderPayload(value, options) {
+    const inspection = inspectProviderPayload(value);
+    const tokens = [...new Set(inspection.promptLeaks.map((leak) => leak.token))];
+    if (tokens.length > 0)
+        throw new ProviderMentionError(options.toolName, tokens);
+    if (options.wire && inspection.placeholderPaths.length > 0) {
+        throw new ProviderPlaceholderError(options.toolName, inspection.placeholderPaths);
+    }
+}

package/dist/provider-status-link.js

@@ -0,0 +1,21 @@
+export function providerStatusUrl(provider, model) {
+    if (provider === "kie")
+        return "https://kie.ai/logs";
+    if (provider !== "fal" || !model || !/^[a-z0-9_-]+(?:\/[a-z0-9_.-]+)+$/iu.test(model))
+        return null;
+    if (model.split("/").some((part) => part === "." || part === ".."))
+        return null;
+    return `https://fal.ai/models/${model.split("/").map(encodeURIComponent).join("/")}/requests`;
+}
+export function parseProviderTaskStatus(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    if (record.provider !== "kie" && record.provider !== "fal")
+        return null;
+    return {
+        provider: record.provider,
+        model: typeof record.model === "string" ? record.model : null,
+        taskId: typeof record.taskId === "string" ? record.taskId : null,
+    };
+}

package/dist/provider-task-record.js

@@ -0,0 +1,78 @@
+function taskRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    if (typeof record.taskId !== "string" || !record.taskId
+        || typeof record.taskType !== "string" || !record.taskType
+        || typeof record.createdAt !== "number"
+        || !record.meta || typeof record.meta !== "object" || Array.isArray(record.meta))
+        return null;
+    return {
+        taskId: record.taskId,
+        taskType: record.taskType,
+        createdAt: record.createdAt,
+        meta: record.meta,
+    };
+}
+export async function preserveProviderTask(engine, task) {
+    const written = await engine.metadata.artifacts.write(task.artifactId, "provider-task", {
+        taskId: task.taskId,
+        taskType: task.taskType,
+        createdAt: task.createdAt,
+        meta: task.meta,
+    });
+    if (!written.ok)
+        throw new Error(written.error.message);
+}
+export async function readProviderTaskRecord(engine, artifactId) {
+    const pending = engine.jobs.pending.read(artifactId);
+    if (pending.ok && pending.value)
+        return pending.value;
+    const saved = await engine.metadata.artifacts.read(artifactId, "provider-task");
+    const record = saved.ok ? taskRecord(saved.value) : null;
+    return record;
+}
+export async function recoverNotebookProviderTask(engine, artifactId) {
+    const pending = engine.jobs.pending.read(artifactId);
+    if (!pending.ok)
+        return false;
+    if (pending.value) {
+        if (pending.value.completing) {
+            const active = engine.jobs.queue.list({ states: ["queued", "running", "completing"] });
+            if (!active.some((job) => job.type === "complete_kie_task"
+                && job.payload.assetId === artifactId
+                && job.payload.taskId === pending.value?.taskId)) {
+                const cleared = engine.jobs.pending.clearCompleting(artifactId);
+                if (!cleared.ok)
+                    throw new Error(cleared.error.message);
+            }
+        }
+        return true;
+    }
+    const failure = engine.jobs.failures.read(artifactId);
+    if (!failure.ok || failure.value)
+        return false;
+    if (engine.jobs.queue.list({
+        states: ["queued", "running", "completing"], artifactId,
+    }).length > 0)
+        return false;
+    const status = await engine.status.get(artifactId);
+    if (!status.ok || status.value === "ready")
+        return false;
+    const record = await readProviderTaskRecord(engine, artifactId);
+    if (!record || record.taskId === "queued")
+        return false;
+    const owner = engine.jobs.artifactWork.begin(artifactId, {
+        kind: "generate", ownerKind: "job", durationMs: 60_000,
+    });
+    if (!owner)
+        return false;
+    const restored = await engine.jobs.pending.write({ artifactId, ...record }, owner.ownerId);
+    if (!restored.ok)
+        throw new Error(restored.error.message);
+    if (!restored.value)
+        return false;
+    await preserveProviderTask(engine, restored.value.task);
+    engine.jobs.artifactWork.complete(artifactId, owner.ownerId);
+    return true;
+}

package/dist/provider-task-status.js

@@ -0,0 +1,47 @@
+import { parseModelId } from "./media/model-id.js";
+import { legacyMediaForTaskType } from "./media/legacy-task-types.js";
+import { readProviderTaskRecord } from "./provider-task-record.js";
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function firstString(...values) {
+    return values.find((value) => typeof value === "string" && value.length > 0) ?? null;
+}
+export async function readProviderTaskStatus(engine, artifactId, hints = {}) {
+    const [saved, payloadResult, idResult] = artifactId ? await Promise.all([
+        readProviderTaskRecord(engine, artifactId),
+        engine.metadata.artifacts.read(artifactId, "generation-payload"),
+        engine.metadata.artifacts.read(artifactId, "kie-task-id"),
+    ]) : [null, null, null];
+    const payload = payloadResult?.ok ? record(payloadResult.value) : {};
+    const storedId = idResult?.ok ? record(idResult.value) : {};
+    const endpoint = firstString(payload.endpoint_id, saved?.meta.falEndpointId, saved?.meta.endpointId, saved?.meta.endpoint_id);
+    const catalogModelId = firstString(saved?.meta.model, hints.model) ?? "";
+    const catalogModel = parseModelId(catalogModelId);
+    if (catalogModelId.includes(":") && !catalogModel)
+        return null;
+    const model = firstString(endpoint, payload.model, catalogModel?.apiId, saved?.meta.apiModel, saved?.meta.model, hints.model);
+    const taskId = firstString(saved?.taskId, storedId.taskId, hints.taskId);
+    if (saved && /^(?:xai|alibaba)_/u.test(saved.taskType))
+        return null;
+    if (saved && saved.taskType !== "media_kie" && saved.taskType !== "isolate_vocals"
+        && !saved.taskType.startsWith("fal_") && legacyMediaForTaskType(saved.taskType) === null)
+        return null;
+    const provider = endpoint || saved?.taskType.startsWith("fal_") ? "fal"
+        : catalogModel?.provider ?? hints.provider ?? (storedId.taskId || saved ? "kie" : null);
+    if (provider !== "kie" && provider !== "fal")
+        return null;
+    return { provider, model, taskId: taskId === "queued" ? null : taskId };
+}
+export async function jobProviderTaskStatus(engine, job) {
+    if (!job.type.startsWith("generate_") && job.type !== "await_notebook_output"
+        && !/^complete_.*task$/u.test(job.type))
+        return null;
+    const catalogModel = parseModelId(firstString(job.payload.model) ?? "");
+    const artifactId = firstString(job.payload.providerArtifactId, job.artifactId, job.payload.imageAssetId, job.payload.imgAssetId, job.payload.vidAssetId, job.payload.assetId);
+    return readProviderTaskStatus(engine, artifactId, {
+        provider: catalogModel?.provider ?? null,
+        model: firstString(job.payload.endpointId, job.payload.modelId, job.payload.model),
+        taskId: firstString(record(job.result).taskId, job.payload.taskId),
+    });
+}

package/dist/provider-usage.js

@@ -0,0 +1,294 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createCost, PRICING, PRICING_AS_OF } from "@apicity/cost";
+import { currentBookContext } from "./book-context.js";
+function installedPackageVersion(name) {
+    let dir = dirname(fileURLToPath(import.meta.resolve(name)));
+    while (dir !== dirname(dir)) {
+        try {
+            const manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+            if (manifest.name === name && manifest.version)
+                return manifest.version;
+        }
+        catch {
+            void 0;
+        }
+        dir = dirname(dir);
+    }
+    return "unknown";
+}
+const COST_PACKAGE_VERSION = installedPackageVersion("@apicity/cost");
+const incomplete = new WeakSet();
+const cost = createCost();
+function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function number(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+}
+function text(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function safeRecord(engine, entry) {
+    try {
+        const result = engine.usage.record(entry);
+        if (result.ok)
+            return;
+    }
+    catch {
+        void 0;
+    }
+    incomplete.add(engine);
+    try {
+        engine.settings.set("usage-incomplete", true);
+    }
+    catch {
+        void 0;
+    }
+}
+export function usageIncomplete(engine) {
+    const scoped = currentBookContext()?.engine ?? engine;
+    return incomplete.has(scoped) || scoped.settings.get("usage-incomplete") === true;
+}
+export async function settleFinishedUsage(engine) {
+    const pending = engine.usage.recent(200).filter((entry) => entry.status === "pending" && entry.externalId !== null && entry.artifactId !== null);
+    for (const entry of pending) {
+        const task = engine.jobs.pending.findByExternalId(entry.externalId);
+        if (!task.ok || task.value)
+            continue;
+        const status = await engine.status.get(entry.artifactId);
+        if (!status.ok)
+            continue;
+        if (status.value === "ready")
+            safeRecord(engine, { ...entry, status: "completed" });
+        else if (status.value === "error")
+            safeRecord(engine, { ...entry, status: "failed" });
+    }
+}
+function reportedTokens(value) {
+    const usage = object(value);
+    const inputTokens = number(usage.input_tokens) ?? number(usage.prompt_tokens) ?? number(usage.inputTokens);
+    const outputTokens = number(usage.output_tokens) ?? number(usage.completion_tokens) ?? number(usage.outputTokens);
+    const details = object(usage.input_tokens_details ?? usage.prompt_tokens_details ?? usage.input_token_details);
+    const cachedTokens = number(details.cached_tokens) ?? number(usage.cached_tokens);
+    return { inputTokens, outputTokens, cachedTokens: cachedTokens !== null && inputTokens !== null ? Math.min(cachedTokens, inputTokens) : cachedTokens };
+}
+function rateFor(provider, model) {
+    const rates = PRICING[provider];
+    return rates?.[model];
+}
+function unknownPrice(warnings = ["Price unavailable for this model"]) {
+    return { costUsd: null, basis: "unknown", rateSource: null, pricingVersion: `apicity-${COST_PACKAGE_VERSION}:${PRICING_AS_OF}`, warnings, units: null, unit: null };
+}
+function tokenPrice(provider, model, tokens) {
+    const rate = rateFor(provider, model);
+    if (rate?.kind !== "tokens" || tokens.inputTokens === null || tokens.outputTokens === null)
+        return unknownPrice();
+    const cached = tokens.cachedTokens ?? 0;
+    const usd = ((tokens.inputTokens - cached) * rate.rate.input + cached * (rate.rate.cacheRead ?? rate.rate.input) + tokens.outputTokens * rate.rate.output) / 1e6;
+    return { ...unknownPrice([]), costUsd: usd, basis: "estimated", rateSource: rate.source.url, unit: "tokens", units: tokens.inputTokens + tokens.outputTokens };
+}
+function priceRequest(provider, model, payload, endpoint, hints) {
+    try {
+        const request = { provider, payload, ...(provider === "fal" ? { endpoint } : {}), ...(hints ? { costHints: hints } : {}) };
+        const estimate = cost.estimate(request);
+        if (estimate.warnings.length || estimate.source === "tokens-heuristic+table")
+            return unknownPrice(estimate.warnings.length ? estimate.warnings : ["Waiting for reported token usage"]);
+        return {
+            ...unknownPrice([]), costUsd: estimate.usd, basis: estimate.source === "free" ? "free" : "estimated",
+            rateSource: rateFor(provider, model)?.source.url ?? null, pricingVersion: `apicity-${COST_PACKAGE_VERSION}:${estimate.rateAsOf}`,
+            units: estimate.breakdown.units ?? null, unit: estimate.breakdown.unit ?? null,
+        };
+    }
+    catch {
+        return unknownPrice();
+    }
+}
+function activityFor(model, path, operation = "") {
+    if (/\/(responses|completions)$/u.test(path) && /chat|rewrite_prompt/u.test(operation))
+        return "chat";
+    if (/transcrib|speech.to.text|analy|describe|tag_|rename|suggest|translate|vision|image.subjects|regions|verify/iu.test(`${operation} ${path}`))
+        return "analysis";
+    if (/video|veo|wan\/|kling|seedance|happyhorse|lipsync/iu.test(`${model} ${path}`))
+        return "video";
+    if (/audio|speech|music|sound|sfx|suno|vocal/iu.test(`${model} ${path}`))
+        return "audio";
+    if (/image|banana|seedream|qwen|flux|ideogram/iu.test(`${model} ${path}`))
+        return "images";
+    return "analysis";
+}
+function isBillable(provider, path, method) {
+    if (method !== "POST")
+        return false;
+    if (provider === "openai" || provider === "xai")
+        return /\/(responses|chat\/completions|images\/(generations|edits)|videos\/(generations|edits|extensions)|audio\/(speech|transcriptions|translations)|embeddings|tts|stt)$/u.test(path);
+    if (provider === "kie")
+        return /\/(createTask|veo\/(generate|extend))$/u.test(path);
+    if (provider === "fal")
+        return /^\/(fal-ai|alibaba)\//u.test(path) && !/\/requests\//u.test(path);
+    if (provider === "alibaba")
+        return path.includes("/services/aigc/");
+    if (provider === "elevenlabs")
+        return /\/(text-to-speech|speech-to-text|speech-to-speech|sound-generation|audio-isolation|music)(\/|$)/u.test(path);
+    return /\/(videos|images)(\/|$)/u.test(path);
+}
+async function payloadOf(input, init) {
+    const body = init?.body;
+    if (typeof body === "string") {
+        try {
+            return object(JSON.parse(body));
+        }
+        catch {
+            return {};
+        }
+    }
+    if (body instanceof FormData)
+        return Object.fromEntries([...body.entries()].filter((entry) => typeof entry[1] === "string"));
+    if (input instanceof Request && input.headers.get("content-type")?.includes("application/json")) {
+        try {
+            return object(await input.clone().json());
+        }
+        catch {
+            return {};
+        }
+    }
+    return {};
+}
+function remoteId(body, url, method) {
+    const data = object(body.data);
+    const output = object(body.output);
+    const pathId = url.searchParams.get("taskId") ?? url.searchParams.get("task_id")
+        ?? (/\/(requests|tasks|jobs|videos)\/([^/]+)(?:\/status)?$/u.exec(url.pathname)?.[2] ?? null);
+    if (method === "GET" && pathId)
+        return decodeURIComponent(pathId);
+    return text(data.taskId) ?? text(data.task_id) ?? text(body.request_id) ?? text(body.job_id)
+        ?? text(output.task_id) ?? text(body.id);
+}
+function responseStatus(body, accepted) {
+    const data = object(body.data);
+    const output = object(body.output);
+    const state = String(body.status ?? data.state ?? data.status ?? output.task_status ?? "").toLowerCase();
+    if (body.error || data.failCode || (typeof body.code === "number" && body.code >= 400) || data.successFlag === 2 || ["failed", "fail", "error"].includes(state))
+        return "failed";
+    if (["cancelled", "canceled"].includes(state))
+        return "cancelled";
+    if (state === "uncertain" || state === "expired")
+        return "uncertain";
+    if (data.successFlag === 1 || ["success", "succeeded", "completed", "done"].includes(state))
+        return "completed";
+    if (["created", "pending", "queued", "in_queue", "running", "in_progress", "processing", "started", "waiting"].includes(state))
+        return "pending";
+    return accepted ? "pending" : "completed";
+}
+function usageOf(body) {
+    return object(body.usage ?? object(body.data).usage ?? object(body.output).usage ?? object(body.response).usage);
+}
+function observedPatch(provider, entry, body, status) {
+    const usage = usageOf(body);
+    const reported = reportedTokens(usage);
+    const tokens = {
+        inputTokens: reported.inputTokens ?? entry.inputTokens ?? null,
+        outputTokens: reported.outputTokens ?? entry.outputTokens ?? null,
+        cachedTokens: reported.cachedTokens ?? entry.cachedTokens ?? null,
+    };
+    const ticks = provider === "xai" ? number(usage.cost_in_usd_ticks) : null;
+    const reportedUsd = number(usage.cost_usd) ?? number(body.cost_usd) ?? number(usage.cost_in_usd) ?? (ticks === null ? null : ticks / 1e10);
+    const hasTokens = reported.inputTokens !== null || reported.outputTokens !== null;
+    const price = reportedUsd !== null
+        ? { costUsd: reportedUsd, basis: "reported", warnings: [] }
+        : entry.tokenBased && hasTokens ? tokenPrice(provider, entry.model, tokens) : {};
+    return { status, ...(hasTokens ? tokens : {}), ...price };
+}
+async function costHints(engine, artifactId) {
+    if (!artifactId)
+        return undefined;
+    const result = await engine.metadata.artifacts.read(artifactId, "generation-cost-hints");
+    if (!result.ok)
+        return undefined;
+    const hints = result.value;
+    const durationSeconds = number(hints.durationSeconds) ?? number(hints.duration);
+    const inputDurationSeconds = number(hints.inputDurationSeconds) ?? number(hints.inputDuration);
+    return { ...(durationSeconds !== null ? { durationSeconds } : {}), ...(inputDurationSeconds !== null ? { inputDurationSeconds } : {}) };
+}
+export function providerUsageFetch(provider, transport = fetch) {
+    return async (input, init) => {
+        const context = currentBookContext();
+        if (!context)
+            return transport(input, init);
+        const engine = context.engine;
+        const url = new URL(input instanceof Request ? input.url : String(input));
+        const method = (init?.method ?? (input instanceof Request ? input.method : "GET")).toUpperCase();
+        const billable = isBillable(provider, url.pathname, method);
+        let entry = null;
+        if (billable) {
+            const payload = await payloadOf(input, init);
+            const endpoint = url.pathname.replace(/^\//u, "");
+            const model = text(payload.model) ?? text(payload.model_id) ?? (provider === "fal" ? endpoint : endpoint.split("/").slice(-2).join("/"));
+            let hints;
+            try {
+                hints = await costHints(engine, context.artifactId);
+            }
+            catch {
+                void 0;
+            }
+            const activity = activityFor(model, url.pathname, context.operation);
+            entry = {
+                id: randomUUID(), provider, model, activity, status: "pending",
+                tokenBased: /\/(responses|completions|embeddings)$/u.test(url.pathname) || rateFor(provider, model)?.kind === "tokens",
+                operation: context.operation ?? null, artifactId: context.artifactId ?? null,
+                ...priceRequest(provider, model, payload, endpoint, hints),
+            };
+            safeRecord(engine, entry);
+        }
+        let response;
+        try {
+            response = await transport(input, init);
+        }
+        catch (error) {
+            if (entry)
+                safeRecord(engine, { ...entry, status: "uncertain", basis: "unknown", warnings: ["Provider outcome unavailable"] });
+            throw error;
+        }
+        try {
+            const json = response.headers.get("content-type")?.includes("json");
+            const body = json ? object(await response.clone().json()) : {};
+            const externalId = remoteId(body, url, method);
+            if (entry) {
+                const accepted = !!externalId && (provider === "kie" || provider === "fal" || /videos|tasks/u.test(url.pathname) || !!object(body.output).task_id);
+                const status = response.ok ? responseStatus(body, accepted) : "failed";
+                safeRecord(engine, { ...entry, ...(externalId ? { externalId } : {}), ...observedPatch(provider, entry, body, status) });
+            }
+            else if (method === "GET" && externalId && response.ok && json) {
+                const existing = engine.usage.find(provider, externalId);
+                if (existing) {
+                    const status = responseStatus(body, /\/status$/u.test(url.pathname));
+                    safeRecord(engine, { ...existing, ...observedPatch(provider, existing, body, status) });
+                }
+            }
+        }
+        catch {
+            if (entry)
+                safeRecord(engine, { ...entry, status: "uncertain", basis: "unknown", warnings: ["Provider usage unavailable"] });
+        }
+        return response;
+    };
+}
+export function recordVoiceUsage(engine, provider, model, sessionId, responseId, response) {
+    const body = object(response);
+    const entry = {
+        id: `voice:${sessionId}:${responseId}`, externalId: `voice:${sessionId}:${responseId}`,
+        provider, model, activity: "voice", tokenBased: true,
+        ...unknownPrice(),
+    };
+    safeRecord(engine, { ...entry, ...observedPatch(provider, entry, body, responseStatus(body, false)) });
+}
+export function recordTranscriptionUsage(engine, model, sessionId, itemId, event) {
+    const body = object(event);
+    const entry = {
+        id: `transcription:${sessionId}:${itemId}`, externalId: `transcription:${sessionId}:${itemId}`,
+        provider: "openai", model, activity: "analysis", tokenBased: true, ...unknownPrice(),
+    };
+    safeRecord(engine, { ...entry, ...observedPatch("openai", entry, body, responseStatus(body, false)) });
+}