@tday-com/mcp 0.0.0-stage → 0.2.0

package/dist/tools-account.d.ts

@@ -0,0 +1,6 @@
+import { z } from "zod";
+import { type Tool } from "./tool-schemas.js";
+export declare const accountTools: Tool[];
+/** The preset sizes `tday_generate_design` accepts (web/src/lib/mcp/v1-image-formats.ts). */
+export declare const IMAGE_FORMATS: readonly ["square", "ig_post", "story", "fb_post", "linkedin_post", "desktop", "a4_page"];
+export declare const imageFormatSchema: z.ZodOptional<z.ZodEnum<["square", "ig_post", "story", "fb_post", "linkedin_post", "desktop", "a4_page"]>>;

package/dist/tools-account.js

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import { api, query } from "./api-client.js";
+import { argsObject, outputSchemas, readOnly, safeIdSchema } from "./tool-schemas.js";
+// What things cost and what an organisation has spent. `tday_whoami` (tools.ts) is the account
+// itself; these two sit beside it. The hosted connector registers the same three
+// (web/src/lib/mcp/remote-account-tools.ts), so keep the descriptions in step.
+export const accountTools = [
+    {
+        name: "tday_get_credit_prices",
+        title: "Credit prices",
+        description: "What each thing costs in credits at today's price list: an image design, an edit, design videos, launch videos (every length, with or without music and voiceover, already added up), a launch video revision, scans, and each plan's monthly credits. Use it to tell the person what something will cost BEFORE starting it, next to the balance from tday_whoami.",
+        inputSchema: argsObject({}),
+        outputSchema: outputSchemas.creditPrices,
+        annotations: readOnly,
+        handler: (_args, config) => api(config, "/api/v1/credits/prices"),
+    },
+    {
+        name: "tday_get_usage",
+        title: "Credit usage",
+        description: "One organisation's credit balance and what it has spent this grant period, by action, by brand and by person, plus a link to its usage page. Pass organizationId from tday_whoami; omitted, the organisation the person owns.",
+        inputSchema: argsObject({
+            organizationId: safeIdSchema.optional().describe("Organisation ID from tday_whoami"),
+        }),
+        outputSchema: outputSchemas.usage,
+        annotations: readOnly,
+        handler: (args, config) => api(config, `/api/v1/usage${query({ organizationId: typeof args.organizationId === "string" ? args.organizationId : undefined })}`),
+    },
+];
+/** The preset sizes `tday_generate_design` accepts (web/src/lib/mcp/v1-image-formats.ts). */
+export const IMAGE_FORMATS = ["square", "ig_post", "story", "fb_post", "linkedin_post", "desktop", "a4_page"];
+export const imageFormatSchema = z
+    .enum(IMAGE_FORMATS)
+    .optional()
+    .describe("Preset size: square 1080x1080, ig_post 1080x1350 (4:5 portrait), story 1080x1920 (9:16), fb_post 1200x630, linkedin_post 1200x627, desktop 1920x1080, a4_page. Portrait, square and story are on the paid plans where the plan gates sizes (tday_whoami output.allSizes); asking for one that is not included is refused with an upgrade link.");

package/dist/tools-demo.d.ts

@@ -0,0 +1,11 @@
+import { type Tool } from "./tool-schemas.js";
+import type { TdayConfig } from "./config.js";
+export declare const demoTools: Tool[];
+/**
+ * Whether the linked account may import demos (GET /api/studio/demo-import: the admin-only
+ * mcp_demo_import flag, which needs walkthrough_demos). Decides whether the demo tools are
+ * listed at all, so a customer's agent is never told they exist. Fails closed: no token, an
+ * older tday without the route, a slow answer or any error hides them. The import routes
+ * still recheck on every call.
+ */
+export declare function demoImportAvailable(config: TdayConfig): Promise<boolean>;

package/dist/tools-demo.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import { api } from "./api-client.js";
+import { argsObject, safeIdSchema, stripPresentationArgs, writeRemote } from "./tool-schemas.js";
+import { importDemoBundle } from "./demo-import.js";
+const metadata = {
+    brandId: safeIdSchema,
+    title: z.string().trim().min(1).max(200),
+    manifest: z.record(z.unknown()).describe("The portable editable/manifest.json produced by the repository demo recorder, not a filesystem path."),
+    assets: z.array(z.object({ name: z.string(), contentType: z.enum(["video/mp4", "audio/mpeg", "image/png"]),
+        sizeBytes: z.number().int().positive().max(104857600), sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    }).strict()).min(3).max(200),
+};
+export const demoTools = [
+    {
+        name: "tday_import_demo", title: "Import local editable demo",
+        description: "Import an already-recorded local branch demo into the linked tday account and return its Studio edit link. Reads only allowlisted media beside editable/manifest.json within the working directory. Uploads directly to storage, preserves narration, source footage and timeline, and never overwrites editor changes on retry. Requires the admin-only mcp_demo_import flag and an owned brand. First record the local feature with the repository demo skill and ElevenLabs; this tool does not record or synthesize speech.",
+        inputSchema: argsObject({ brandId: safeIdSchema, title: z.string().trim().min(1).max(200), manifestPath: z.string().min(1) }),
+        outputSchema: z.object({ projectId: z.string(), editorUrl: z.string(), reused: z.boolean() }),
+        annotations: { ...writeRemote, idempotentHint: true },
+        handler: (args, config) => importDemoBundle(config, String(args.manifestPath), String(args.brandId), String(args.title)),
+    },
+    {
+        name: "tday_prepare_demo_import", title: "Prepare editable demo upload",
+        description: "Prepare direct uploads for a portable narrated demo bundle. Admin-only feature flag, active admin and owned brand required. Supply manifest JSON and each allowlisted asset's byte length and SHA256. PUT each local file to its returned uploadUrl with the returned headers, without the tday bearer token. Then call tday_complete_demo_import with the same metadata and ticket. A reused result already contains the edit link. Does not read local paths or record a demo.",
+        inputSchema: argsObject(metadata), outputSchema: z.object({}).passthrough(), annotations: writeRemote,
+        handler: (args, config) => api(config, "/api/studio/demo-import/prepare", { method: "POST", body: JSON.stringify(stripPresentationArgs(args)) }),
+    },
+    {
+        name: "tday_complete_demo_import", title: "Complete editable demo import",
+        description: "Verify all uploaded demo assets and create an editable Studio project, returning editorUrl. Pass the exact metadata from prepare and its unexpired ticket. Rechecks the admin-only feature flag and ownership. Retries reuse the project without overwriting human edits. Does not publish to social networks or enqueue a generation.",
+        inputSchema: argsObject({ ...metadata, ticket: z.string().min(1).max(4096) }),
+        outputSchema: z.object({ projectId: z.string(), editorUrl: z.string(), reused: z.boolean() }), annotations: { ...writeRemote, idempotentHint: true },
+        handler: (args, config) => api(config, "/api/studio/demo-import/complete", { method: "POST", body: JSON.stringify(stripPresentationArgs(args)) }),
+    },
+];
+/** Longest the server waits on start for the availability answer before hiding the tools. */
+const AVAILABILITY_TIMEOUT_MS = 5_000;
+/**
+ * Whether the linked account may import demos (GET /api/studio/demo-import: the admin-only
+ * mcp_demo_import flag, which needs walkthrough_demos). Decides whether the demo tools are
+ * listed at all, so a customer's agent is never told they exist. Fails closed: no token, an
+ * older tday without the route, a slow answer or any error hides them. The import routes
+ * still recheck on every call.
+ */
+export async function demoImportAvailable(config) {
+    if (!config.token)
+        return false;
+    try {
+        const result = await api(config, "/api/studio/demo-import", {
+            signal: AbortSignal.timeout(AVAILABILITY_TIMEOUT_MS),
+        });
+        return result?.available === true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/tools-knowledge.d.ts

@@ -0,0 +1,4 @@
+import { type Tool } from "./tool-schemas.js";
+/** The frontmatter vocabulary. Closed, so `type` stays a badge somebody can read. */
+export declare const KNOWLEDGE_ENTRY_TYPES: readonly ["invariant", "trap", "history", "decision"];
+export declare const knowledgeTools: Tool[];

package/dist/tools-knowledge.js

@@ -0,0 +1,111 @@
+import { z } from "zod";
+import { api, query } from "./api-client.js";
+import { argsObject, outputSchemas, readOnly, stripPresentationArgs, writeRemote, } from "./tool-schemas.js";
+// The knowledge-base tools: record a fact the moment it is learned, and check what is
+// already recorded before recording a near-duplicate. Split from tools.ts per the
+// 500-line ceiling, the same way tool-schemas.ts and api-client.ts were.
+//
+// Both go through /api/v1/knowledge-entries, the bearer-key endpoint next to
+// /api/v1/generate. Note what is NOT in the input schemas: `source`. The server stamps
+// every write as "mcp" from the route it arrived on, so a caller cannot label its own
+// entry as reviewed-by-something-else — and argsObject is strict, so passing it is a
+// validation error rather than a silently ignored field.
+/**
+ * The byte ceiling /api/v1/knowledge-entries enforces before it parses (`MAX_BODY_BYTES`
+ * in web/src/app/api/v1/knowledge-entries/route.ts). Mirrored, not lowered.
+ *
+ * The field limits below are in CHARACTERS and the cap is in BYTES, so the two only agree
+ * for ASCII: every field at its maximum serialises to 30,274 bytes of ASCII — 46% of the
+ * cap, so the schema cannot overrun it on its own — but the same shape with a CJK body is
+ * 70,274, and one full of control characters (escaped to \uXXXX, six bytes each) is 120,011.
+ * Those pass validation and would come back as a bare 400 about a limit the caller was
+ * never told, so measure the serialised payload here and name the field to shrink.
+ */
+const MAX_REQUEST_BYTES = 64 * 1024;
+/** The frontmatter vocabulary. Closed, so `type` stays a badge somebody can read. */
+export const KNOWLEDGE_ENTRY_TYPES = ["invariant", "trap", "history", "decision"];
+const entryTypeSchema = z
+    .enum(KNOWLEDGE_ENTRY_TYPES)
+    .describe("invariant (a rule that must hold), trap (a way this bites you), history (why it ended up like this), or decision (a choice and its reasoning).");
+export const knowledgeTools = [
+    {
+        name: "tday_search_knowledge_entries",
+        title: "Search knowledge entries",
+        description: "Search the tday codebase knowledge base — reviewed entries and unreviewed drafts together — by free text. Call this BEFORE tday_create_knowledge_entry: if a hit with \"draft\": true already states the fact, reuse that slug to update it instead of adding a near-duplicate. A hit with \"draft\": false is a reviewed, committed entry and is READ-ONLY here — recording its slug fails with 409; correct it in a pull request against its `path`, or record the new fact under a different slug. Bodies are truncated to 1200 characters.",
+        inputSchema: argsObject({
+            query: z
+                .string()
+                .trim()
+                .min(1)
+                .max(500)
+                .optional()
+                .describe("Free text, matched against slug, name, description, tracked paths, and body. Omit to list what exists."),
+            type: entryTypeSchema.optional().describe("Restrict results to one entry type."),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .default(10)
+                .describe("Maximum entries to return. Defaults to 10."),
+        }),
+        outputSchema: outputSchemas.searchKnowledgeEntries,
+        annotations: readOnly,
+        handler: (args, config) => api(config, `/api/v1/knowledge-entries${query({
+            q: args.query,
+            type: args.type,
+            limit: Number(args.limit),
+        })}`),
+    },
+    {
+        name: "tday_create_knowledge_entry",
+        title: "Record knowledge entry",
+        description: "Record something learned about the tday codebase as a draft knowledge entry, visible in the knowledge graph immediately and marked as unreviewed. Use it the moment an investigation produces a durable fact, not at the end of a session. Search first with tday_search_knowledge_entries; recording an existing DRAFT's slug (a hit with \"draft\": true) UPDATES that entry rather than creating a second one. Only drafts can be updated: a reviewed, committed entry (\"draft\": false) is read-only through this tool and its slug is rejected with 409 — retrying it will not succeed, so either edit that file in a pull request or pick a different slug. Requires a tday staff account.",
+        inputSchema: argsObject({
+            name: z
+                .string()
+                .trim()
+                .min(1)
+                .max(120)
+                .describe("Short title for the fact, for example 'Money is stored in microdollars'."),
+            description: z
+                .string()
+                .trim()
+                .min(1)
+                .max(300)
+                .describe("One line, read when deciding whether this entry is relevant."),
+            type: entryTypeSchema,
+            body: z
+                .string()
+                .trim()
+                .min(1)
+                .max(20_000)
+                .describe("Markdown. State the fact, why it is that way, and what to do about it. [[other-entry-slug]] links become edges in the graph."),
+            tracks: z
+                .array(z.string().trim().min(1).max(300))
+                .max(32)
+                .optional()
+                .describe("Repo-relative paths whose change would make this entry false, for example web/src/lib/pricing/constants.ts. Paths that cannot be normalised are dropped."),
+            slug: z
+                .string()
+                .trim()
+                .min(2)
+                .max(80)
+                .optional()
+                .describe("Kebab-case key, for example money-in-microdollars. Derived from name when omitted. Reuse an existing draft's slug to correct it."),
+        }),
+        outputSchema: outputSchemas.createKnowledgeEntry,
+        annotations: writeRemote,
+        handler: (args, config) => {
+            const payload = JSON.stringify(stripPresentationArgs(args));
+            const bytes = new TextEncoder().encode(payload).length;
+            if (bytes > MAX_REQUEST_BYTES) {
+                const body = typeof args.body === "string" ? args.body : "";
+                throw new Error(`This entry serialises to ${bytes} bytes and /api/v1/knowledge-entries accepts at most ${MAX_REQUEST_BYTES}. ` +
+                    `The per-field limits count characters, not bytes, so non-ASCII text can pass them and still be too large. ` +
+                    `Shorten body (${body.length} characters) and retry.`);
+            }
+            return api(config, "/api/v1/knowledge-entries", { method: "POST", body: payload });
+        },
+    },
+];

package/dist/tools-launch.d.ts

@@ -0,0 +1,4 @@
+import { type Tool } from "./tool-schemas.js";
+/** A long (50s) film at 1080p is tens of megabytes; this is a generous ceiling, not a target. */
+export declare const MAX_VIDEO_BYTES: number;
+export declare const launchTools: Tool[];

package/dist/tools-launch.js

@@ -0,0 +1,365 @@
+import { constants } from "node:fs";
+import { open, rm } from "node:fs/promises";
+import { z } from "zod";
+import { api } from "./api-client.js";
+import { prepareOutputFilePath, validateImageUrl } from "./download-safety.js";
+import { argsObject, readOnly, safeIdSchema, safePath, writeLocal, writeRemote, } from "./tool-schemas.js";
+// The launch-video (launch film) tools. They drive the same routes tday's Launch page
+// does, so tday's own pipeline writes the brief, storyboard, motion, score and narration:
+// the caller supplies a subject in words and the creative axes, never HTML, a screenshot
+// or a file. Split from tools.ts per the 500-line ceiling, like tools-knowledge.ts.
+//
+// The hosted connector has the same four tools (web/src/lib/mcp/remote-launch-tools.ts).
+// The two cannot share code, so keep them in step. The option vocabularies below mirror
+// web/src/lib/showcase/video-*.ts; an unknown voice id falls back to the default voice there.
+/** The features route's own title cap (web/src/app/api/showcase/features/route.ts). */
+const MAX_TITLE_CHARS = 160;
+const MAX_DESCRIPTION_CHARS = 4000;
+/** Creative notes ride inside every agent's prompt, so the route caps them (video-direction.ts). */
+const MAX_DIRECTION_CHARS = 600;
+/** A long (50s) film at 1080p is tens of megabytes; this is a generous ceiling, not a target. */
+export const MAX_VIDEO_BYTES = 250 * 1024 * 1024;
+const MUSIC_MOODS = ["Cinematic", "Upbeat", "Minimal", "Warm", "Driving"];
+const VOICES = "Reece (OvzQwLvkMu8kuS6YKiR6), warm conversational narrator; Ivy (MClEFoImJXBTgLwdLI5n), bright friendly presenter; " +
+    "Janet (21m00Tcm4TlvDq8ikWAM), warm expressive explainer; Sarah (EXAVITQu4vr4xnSDxMaL), upbeat lively presenter; " +
+    "Craig (TxGEqnHWrfWFTfGW9XjX), deep polished broadcast voice";
+const POLL_GUIDANCE = "Poll tday_poll_launch_video with this videoId every 20-30 seconds until it is ready.";
+const VOICEOVER_NOT_INCLUDED = "Voiceover is not included on this organisation's plan, so the film is silent and no voice was charged.";
+const videoIdSchema = safeIdSchema.describe("videoId returned by tday_create_launch_video");
+const outputSchemas = {
+    create: z
+        .object({ videoId: z.string(), status: z.string(), narration: z.string(), reviewUrl: z.string() })
+        .passthrough(),
+    poll: z
+        .object({ videoId: z.string(), status: z.string(), state: z.string(), terminal: z.boolean(), reviewUrl: z.string() })
+        .passthrough(),
+    mp4: z
+        .object({
+        videoId: z.string(),
+        versionId: z.string(),
+        fps: z.number(),
+        state: z.enum(["ready", "rendering", "failed"]),
+        mp4Url: z.string().optional(),
+        progress: z.number().nullable().optional(),
+        saved: z.boolean().optional(),
+        path: z.string().optional(),
+        size: z.number().optional(),
+    })
+        .passthrough(),
+    revise: z.object({ videoId: z.string(), status: z.string(), reviewUrl: z.string() }).passthrough(),
+};
+/** How long a launch film's first export usually takes; later asks return the stored file. */
+const FIRST_EXPORT = "The first request for a cut at a frame rate renders its file, which usually takes a minute or two";
+export const launchTools = [
+    {
+        name: "tday_create_launch_video",
+        title: "Create launch video",
+        description: "Make a launch video: a short animated film announcing a feature or product, in the brand's own look. tday's pipeline writes the brief, storyboard, motion, music and narration from the title and description; describe the subject well and pick the options. " +
+            "It spends credits from the brand's organisation: a standard (20s), scored, silent film is 40 credits, and a voiceover or another length changes that (tday_get_credit_prices has the full list). " +
+            "A 402 means the balance cannot cover it: nothing was started, so do not retry. Returns a videoId and a reviewUrl at once; the film takes about 2-5 minutes, so poll tday_poll_launch_video.",
+        inputSchema: argsObject({
+            brandId: safeIdSchema.describe("Brand ID from tday_list_brands. The film uses this brand's colours, fonts and logo."),
+            title: z.string().trim().min(1).max(MAX_TITLE_CHARS).describe("The feature or product the film launches, as a short name."),
+            description: z
+                .string()
+                .trim()
+                .min(1)
+                .max(MAX_DESCRIPTION_CHARS)
+                .describe("What the feature or product does and who it is for. The film's brief is written from this, so be specific."),
+            length: z
+                .enum(["short", "standard", "long"])
+                .default("standard")
+                .describe("short (about 10s), standard (about 20s, the default) or long (about 50s)."),
+            narration: z
+                .enum(["silent", "voiceover"])
+                .default("silent")
+                .describe("silent (music and motion carry it, the default) or voiceover (narrated, with captions; costs more)."),
+            music: z.enum(["score", "none"]).default("score").describe("score (a bed written to the film's length, the default) or none."),
+            musicMood: z.enum(MUSIC_MOODS).optional().describe("A mood for the score. Omit to let the planner choose."),
+            voiceId: safeIdSchema.optional().describe(`The narrator of a voiceover film. Omit for the default. One of: ${VOICES}.`),
+            direction: z
+                .string()
+                .trim()
+                .min(1)
+                .max(MAX_DIRECTION_CHARS)
+                .optional()
+                .describe("Optional creative notes in plain words, for example 'lead on the scrubbing, end on the call to action'."),
+        }),
+        outputSchema: outputSchemas.create,
+        annotations: writeRemote,
+        handler: async (args, config) => {
+            const saved = await api(config, "/api/showcase/features", {
+                method: "POST",
+                body: JSON.stringify({ brandId: args.brandId, title: args.title, description: args.description, typeId: null }),
+            });
+            const featureId = saved?.feature?.id;
+            if (typeof featureId !== "string")
+                throw new Error("tday could not start that film. Try again in a moment.");
+            const created = await api(config, safePath("/api/showcase/features/:id/create-launch-video", { id: featureId }), { method: "POST", body: JSON.stringify(launchAxes(args)) }).catch((error) => {
+                throw new Error(`${error instanceof Error ? error.message : String(error)} ${subjectSaved(args.title)}`);
+            });
+            const videoId = created?.runFeatureId;
+            if (typeof videoId !== "string")
+                throw new Error("tday could not start that film. Try again in a moment.");
+            const narration = created?.narration === "voiceover" || created?.narration === "silent" ? created.narration : args.narration;
+            return {
+                videoId,
+                status: "queued",
+                length: args.length,
+                narration,
+                music: args.music,
+                reviewUrl: reviewUrl(config, videoId),
+                ...(args.narration === "voiceover" && narration === "silent" ? { note: VOICEOVER_NOT_INCLUDED } : {}),
+                next: `A film takes about 2-5 minutes. ${POLL_GUIDANCE}`,
+            };
+        },
+    },
+    {
+        name: "tday_poll_launch_video",
+        title: "Poll launch video",
+        description: "Check a launch video made with tday_create_launch_video or revised with tday_revise_launch_video. state is in_progress, ready or failed; terminal is true once it is ready or failed. " +
+            "Poll every 20-30 seconds while it is in progress. When it is ready, watch it at reviewUrl or call tday_get_launch_video_mp4 for the MP4 file. Spends no credits.",
+        inputSchema: argsObject({ videoId: videoIdSchema }),
+        outputSchema: outputSchemas.poll,
+        annotations: readOnly,
+        handler: async (args, config) => {
+            const videoId = String(args.videoId);
+            const payload = await api(config, safePath("/api/showcase/videos/:videoId", args));
+            return summarizeLaunchVideo(videoId, payload ?? {}, reviewUrl(config, videoId));
+        },
+    },
+    {
+        name: "tday_get_launch_video_mp4",
+        title: "Get launch video MP4",
+        description: "Get a ready launch video as an MP4 file URL. A launch video is ready before its file: " + FIRST_EXPORT + ", so this answers state rendering " +
+            "(with progress) until the file exists - call it again every 20-30 seconds until state is ready. Later requests return the stored file at once. Spends no credits. " +
+            "If state is failed, call it again with retry: true. versionId defaults to the newest ready cut (readyVersionId from tday_poll_launch_video). " +
+            `Pass download: true to also save it inside the current working directory once it is ready (at most ${MAX_VIDEO_BYTES / 1024 / 1024}MB).`,
+        inputSchema: argsObject({
+            videoId: videoIdSchema,
+            versionId: safeIdSchema.optional().describe("A cut's versionId from tday_poll_launch_video. Omit for the newest ready cut."),
+            fps: z.union([z.literal(60), z.literal(30)]).default(60).describe("The file's frame rate: 60 (the default, smoothest) or 30 (a smaller file). Older cuts that cannot be rendered again offer only 60 and answer 409 for 30."),
+            retry: z.boolean().default(false).describe("Ask again after state failed. Defaults to false."),
+            download: z.boolean().default(false).describe("Also save the MP4 into the current working directory. Defaults to false."),
+            filePath: z
+                .string()
+                .trim()
+                .min(1)
+                .max(500)
+                .optional()
+                .describe("Where to save it, relative to cwd. Defaults to ./tday-launch-videos/<videoId>-<versionId>.mp4 (<videoId>-<versionId>-30fps.mp4 at 30 fps, so both rates can sit side by side). Only used with download."),
+            overwrite: z.boolean().default(false).describe("Whether to overwrite an existing regular file. Defaults to false for safety."),
+        }),
+        outputSchema: outputSchemas.mp4,
+        annotations: writeLocal,
+        handler: async (args, config) => {
+            const videoId = String(args.videoId);
+            const versionId = typeof args.versionId === "string" ? args.versionId : await newestReadyVersion(config, videoId);
+            const fps = args.fps === 30 ? 30 : 60;
+            // Asks for the file: the stored one, or its export is started (or joined while it renders).
+            const answer = await api(config, safePath("/api/showcase/videos/:videoId/render", args), {
+                method: "POST",
+                body: JSON.stringify({ versionId, ...(fps === 30 ? { fps } : {}), ...(args.retry ? { retry: true } : {}) }),
+            });
+            const waiting = exportWaiting(answer, { videoId, versionId, fps, reviewUrl: reviewUrl(config, videoId) });
+            if (waiting)
+                return waiting;
+            const mp4Url = answer?.mp4Url;
+            if (typeof mp4Url !== "string")
+                throw new Error("tday could not prepare the video. Try again in a moment.");
+            const film = { videoId, versionId, fps, state: "ready", mp4Url, reviewUrl: reviewUrl(config, videoId) };
+            if (!args.download)
+                return film;
+            const filePath = typeof args.filePath === "string" ? args.filePath : `./tday-launch-videos/${videoId}-${versionId}${fps === 30 ? "-30fps" : ""}.mp4`;
+            return { ...film, saved: true, ...(await saveVideo(mp4Url, filePath, Boolean(args.overwrite))) };
+        },
+    },
+    {
+        name: "tday_revise_launch_video",
+        title: "Revise launch video",
+        description: "Make a new cut of a ready launch video from notes, for example 'slow the ending down' or 'lead with the search box'. The kept film is edited to the notes, so the rest stays as it was. " +
+            "It spends tweak credits from the brand's organisation (13 credits for a standard film; tday_get_credit_prices has the full list), and a 402 means the balance cannot cover it. " +
+            "A 409 means a cut is already being made: poll until it finishes. The previous cut stays available while the new one is made. " + POLL_GUIDANCE,
+        inputSchema: argsObject({
+            videoId: videoIdSchema,
+            notes: z.string().trim().min(1).max(MAX_DIRECTION_CHARS).describe("What to change, in plain words."),
+        }),
+        outputSchema: outputSchemas.revise,
+        annotations: writeRemote,
+        handler: async (args, config) => {
+            const videoId = String(args.videoId);
+            const cut = await api(config, safePath("/api/showcase/videos/:videoId/regenerate", args), {
+                method: "POST",
+                body: JSON.stringify({ instructions: args.notes }),
+            });
+            return {
+                videoId,
+                ...(typeof cut?.versionId === "string" ? { versionId: cut.versionId } : {}),
+                status: "queued",
+                reviewUrl: reviewUrl(config, videoId),
+                next: `A new cut takes a few minutes. ${POLL_GUIDANCE}`,
+            };
+        },
+    },
+];
+/**
+ * The subject is saved before the film is started, so a refused start (out of credits, a plan
+ * without the Launch page) leaves it on the brand's Launch page, as a subject a film can be made
+ * from later. Said, so the row is not a surprise. MCP keys cannot delete catalog features, on
+ * purpose: that scope would let a prompt-injected assistant remove any brand's launch features.
+ */
+function subjectSaved(title) {
+    return `The subject "${String(title)}" was saved on the brand's Launch page, where a film can be made from it later.`;
+}
+/** The create route's body: the axes, with the optional ones only when they were given. */
+function launchAxes(args) {
+    return {
+        length: args.length,
+        narration: args.narration,
+        music: args.music,
+        ...(args.musicMood ? { musicMood: args.musicMood } : {}),
+        ...(args.voiceId ? { voiceId: args.voiceId } : {}),
+        ...(args.direction ? { direction: args.direction } : {}),
+    };
+}
+function reviewUrl(config, videoId) {
+    return `${config.webBaseUrl}/showcase/review/${encodeURIComponent(videoId)}`;
+}
+async function newestReadyVersion(config, videoId) {
+    const payload = await api(config, safePath("/api/showcase/videos/:videoId", { videoId }));
+    const versionId = payload?.video?.versionId;
+    if (typeof versionId !== "string") {
+        throw new Error("This launch video has no finished cut yet. Poll tday_poll_launch_video until it is ready, then try again.");
+    }
+    return versionId;
+}
+/**
+ * The review payload as a poll answer. The newest version decides the state (a revision in
+ * flight is in progress even while an older cut is watchable); `readyVersionId` is the newest
+ * cut that can be watched or downloaded, which a failed revision leaves in place.
+ */
+function summarizeLaunchVideo(videoId, payload, url) {
+    const status = stringOr(payload.feature?.status, "unknown");
+    const first = Array.isArray(payload.versions) ? payload.versions[0] : undefined;
+    const latest = typeof first === "object" && first !== null ? first : null;
+    const latestStatus = stringOr(latest?.status, null);
+    const readyVersionId = stringOr(payload.video?.versionId, null);
+    const state = launchState(status, latestStatus);
+    const failureMessage = state === "failed" ? stringOr(latest?.failureMessage, null) : null;
+    // No `mp4Url` here: the review payload's MP4 is the stored file, the clean preview. The
+    // file an agent may take away is the MP4 tool's, which asks the render route for the
+    // DOWNLOAD (badged for a brand whose downloads carry the Free-tier badge).
+    const durationMs = typeof payload.video?.durationMs === "number" ? payload.video.durationMs : null;
+    return {
+        videoId,
+        ...(typeof payload.feature?.title === "string" ? { title: payload.feature.title } : {}),
+        status,
+        state,
+        terminal: state !== "in_progress",
+        latestVersion: latest
+            ? { versionId: stringOr(latest.versionId, null), versionNumber: latest.versionNumber ?? null, status: latestStatus }
+            : null,
+        ...(readyVersionId ? { readyVersionId } : {}),
+        ...(durationMs !== null ? { durationMs } : {}),
+        ...(failureMessage ? { failureMessage } : {}),
+        reviewUrl: url,
+        next: nextStep(state, readyVersionId),
+    };
+}
+/** An export still rendering, or one that failed, as the MP4 tool's answer; null when the file is ready. */
+function exportWaiting(answer, film) {
+    if (answer?.status === "rendering" || answer?.status === "none") {
+        const progress = typeof answer.progress === "number" ? answer.progress : null;
+        return {
+            ...film,
+            state: "rendering",
+            progress,
+            next: `The file is being rendered${progress === null ? "" : ` (${Math.round(progress * 100)}% done)`}. ${FIRST_EXPORT}. Call tday_get_launch_video_mp4 again in 20-30 seconds.`,
+        };
+    }
+    if (answer?.status === "failed") {
+        return {
+            ...film,
+            state: "failed",
+            error: typeof answer.error === "string" ? answer.error : "The file could not be rendered.",
+            next: "The file could not be rendered and spent no credits. Call tday_get_launch_video_mp4 again with retry: true to try again.",
+        };
+    }
+    return null;
+}
+function launchState(featureStatus, latestStatus) {
+    if (latestStatus === "ready")
+        return "ready";
+    if (latestStatus === "failed" || featureStatus === "failed")
+        return "failed";
+    if (!latestStatus && (featureStatus === "review" || featureStatus === "published"))
+        return "ready";
+    return "in_progress";
+}
+function nextStep(state, readyVersionId) {
+    if (state === "ready") {
+        return "Ready. Watch it at reviewUrl, call tday_get_launch_video_mp4 for the MP4 file (its first request renders the file, usually a minute or two), or tday_revise_launch_video to change it.";
+    }
+    if (state === "in_progress")
+        return "Still being made. Poll again in 20-30 seconds.";
+    return readyVersionId
+        ? "This cut failed and was not charged. The previous cut is still available: tday_get_launch_video_mp4 returns it, and tday_revise_launch_video can try the change again."
+        : "This film failed and was not charged. Start a new one with tday_create_launch_video.";
+}
+function stringOr(value, fallback) {
+    return typeof value === "string" && value ? value : fallback;
+}
+/**
+ * Save the film inside the working directory. The same guards as tday_download_image
+ * (download-safety.ts: the tday CDN allowlist, the cwd sandbox, no symlinks, no silent
+ * overwrite), but streamed to disk rather than buffered, since a film is far larger than an
+ * image. A refused or interrupted download leaves no partial file behind.
+ */
+async function saveVideo(mp4Url, rawPath, overwrite) {
+    const url = validateImageUrl(mp4Url);
+    const filePath = await prepareOutputFilePath(rawPath, { overwrite });
+    const res = await fetch(url.href);
+    if (res.url)
+        validateImageUrl(res.url);
+    if (!res.ok)
+        throw new Error(`Failed to download the video: ${res.status} ${res.statusText}`);
+    const declared = Number(res.headers.get("content-length") ?? 0);
+    if (Number.isFinite(declared) && declared > MAX_VIDEO_BYTES) {
+        throw new Error(`The video exceeds the ${MAX_VIDEO_BYTES / 1024 / 1024}MB download limit. Use mp4Url instead.`);
+    }
+    const contentType = res.headers.get("content-type")?.toLowerCase();
+    if (contentType && !/^(video\/|application\/octet-stream|binary\/octet-stream)/.test(contentType)) {
+        throw new Error(`The download is not a video (content-type: ${contentType}).`);
+    }
+    const reader = res.body?.getReader();
+    if (!reader)
+        throw new Error("No response body from the video URL.");
+    const flags = constants.O_WRONLY |
+        constants.O_CREAT |
+        (overwrite ? constants.O_TRUNC : constants.O_EXCL) |
+        (constants.O_NOFOLLOW ?? 0);
+    const handle = await open(filePath, flags, 0o600);
+    let size = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > MAX_VIDEO_BYTES) {
+                throw new Error(`The video exceeds the ${MAX_VIDEO_BYTES / 1024 / 1024}MB download limit. Use mp4Url instead.`);
+            }
+            await handle.write(value);
+        }
+    }
+    catch (error) {
+        await handle.close();
+        await rm(filePath, { force: true });
+        throw error;
+    }
+    finally {
+        reader.releaseLock();
+    }
+    await handle.close();
+    return { path: filePath, size };
+}

package/dist/tools.d.ts

@@ -0,0 +1,15 @@
+import type { TdayConfig } from "./config.js";
+import { type Tool } from "./tool-schemas.js";
+export type { ResponseFormat, Tool } from "./tool-schemas.js";
+export { responseFormatFromArgs, safePath } from "./tool-schemas.js";
+export { ALLOWED_IMAGE_HOSTS, MAX_IMAGE_BYTES, prepareOutputFilePath, sandboxFilePath, validateImageUrl, } from "./download-safety.js";
+export { formatToolResultText, stringifyResult, toStructuredContent, } from "./result-format.js";
+export { knowledgeTools, KNOWLEDGE_ENTRY_TYPES } from "./tools-knowledge.js";
+export declare const tools: Tool[];
+/**
+ * The tools this account is shown: every tool, minus the demo-import tools unless the
+ * account may import (tools-demo.ts). `tools` stays the full set so `callTool` can still
+ * name them; their routes refuse an account without access.
+ */
+export declare function listedTools(config: TdayConfig): Promise<Tool[]>;
+export declare function callTool(name: string, args: Record<string, unknown>, config: TdayConfig): Promise<unknown>;