@sync.so/mcp-server 0.1.3 → 0.2.0

package/dist/tools/generator.js

@@ -1,27 +1,129 @@
 import { z } from 'zod';
+import { currentToolName } from '../tool-names.js';
+import { estimateDurationInputs, resolveEstimateDuration } from './estimate-duration.js';
 import { getOverride } from './overrides.js';
+const voiceCloneSourceSchema = z
+    .object({
+    url: z
+        .url()
+        .optional()
+        .describe('Sync-hosted audio/video sample URL. Supply url or assetId, not both.'),
+    sampleUrls: z
+        .array(z.url())
+        .min(1)
+        .max(10)
+        .optional()
+        .describe('Sync-hosted samples for one reusable voice; use instead of url or assetId.'),
+    assetId: z
+        .uuid()
+        .optional()
+        .describe('Accessible audio/video sample asset ID. Supply assetId or url, not both.'),
+})
+    .refine((input) => [input.url, input.assetId, input.sampleUrls].filter((value) => value !== undefined).length ===
+    1, {
+    message: 'Provide exactly one of url, assetId or sampleUrls for voice samples.',
+});
 export function generateTools(operations, httpClient) {
     return operations.map((op) => generateTool(op, httpClient));
 }
+/**
+ * Behaviour hints required by the ChatGPT and Claude app/connector directories
+ * (missing/incorrect annotations are a top review-rejection cause). Derived
+ * from the HTTP verb: reads are read-only; writes modify external Sync state,
+ * so they are destructive and open-world.
+ */
+export function deriveAnnotations(method, toolName) {
+    if (method === 'get' ||
+        ['generations_estimate-cost', 'generations_estimate'].includes(toolName ?? '')) {
+        return { readOnlyHint: true, destructiveHint: false, openWorldHint: false };
+    }
+    if (method === 'delete') {
+        return { readOnlyHint: false, destructiveHint: true, openWorldHint: true };
+    }
+    // No idempotency contract for generation or other create/update operations.
+    return { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true };
+}
 function generateTool(operation, httpClient) {
     const name = operationIdToToolName(operation.operationId);
     const override = getOverride(name);
     const description = override?.description ?? truncate(operation.summary, 200);
     const inputSchema = buildInputSchema(operation);
+    const admission = admissionKey(operation);
+    if (admission)
+        inputSchema.idempotencyKey = admission.schema;
+    const estimatesCost = ['generations_estimate-cost', 'generations_estimate'].includes(name);
+    if (estimatesCost) {
+        if (inputSchema.duration) {
+            inputSchema.duration = inputSchema.duration
+                .optional()
+                .describe('Billable output seconds, or source seconds for translate-and-dub. For replacement speech, supply script or measured audioDuration instead. Never use the source video length for a shorter replacement script.');
+        }
+        Object.assign(inputSchema, estimateDurationInputs);
+    }
+    if (name === 'voices_clone') {
+        // Flattening the API's allOf/oneOf alternatives makes both sources required.
+        // Keep the descriptor flat, then enforce the exclusive choice before writing.
+        Object.assign(inputSchema, voiceCloneSourceSchema.shape);
+    }
     return {
         name,
+        title: override?.title ?? titleForToolName(name),
         description,
         inputSchema,
-        handler: async (args) => {
-            const path = buildPath(operation.path, args);
-            const query = buildQuery(operation.parameters, args);
-            const body = buildBody(operation, args);
-            return httpClient.request(operation.method, path, { query, body });
+        outputSchema: override?.outputSchema,
+        annotations: deriveAnnotations(operation.method, name),
+        handler: async (args, context) => {
+            if (name === 'voices_clone')
+                voiceCloneSourceSchema.parse(args);
+            const prepared = prepareAdmission(args, admission);
+            const estimate = estimatesCost ? resolveEstimateDuration(prepared.args) : undefined;
+            const requestArgs = estimate?.args ?? prepared.args;
+            if (estimatesCost && inputSchema.duration && requestArgs.duration === undefined)
+                throw new Error('Supply duration, script or audioDuration for a cost estimate.');
+            const path = buildPath(operation.path, requestArgs);
+            const query = buildQuery(operation.parameters, requestArgs);
+            const body = buildBody(operation, requestArgs);
+            const result = await httpClient.request(operation.method, path, {
+                query,
+                body,
+                ...prepared.headers,
+                signal: context?.signal,
+            });
+            if (!estimate?.durationEstimate)
+                return result;
+            return {
+                ...z.record(z.string(), z.unknown()).parse(result),
+                durationEstimate: estimate.durationEstimate,
+            };
         },
     };
 }
-export function operationIdToToolName(operationId) {
-    // "GenerateController_createGeneration" → "generate_create-generation"
+/** Generated stdio writes must carry API admission keys as headers, not JSON fields. */
+function admissionKey(operation) {
+    const parameter = operation.parameters.find((entry) => entry.in === 'header' && entry.name.toLowerCase() === 'idempotency-key');
+    if (!parameter)
+        return undefined;
+    const key = parameter.schema.format === 'uuid' ? z.uuid() : z.string().regex(/^[A-Za-z0-9._~-]{1,128}$/);
+    return {
+        name: parameter.name,
+        schema: (parameter.required ? key : key.optional()).describe('Persist before creation. Reuse this same key and identical inputs only to reconcile uncertain admission; do not create a new key for a retry.'),
+    };
+}
+function prepareAdmission(args, admission) {
+    if (!admission)
+        return { args, headers: {} };
+    const { idempotencyKey, ...fields } = args;
+    const key = admission.schema.parse(idempotencyKey);
+    return {
+        args: fields,
+        headers: key === undefined ? {} : { headers: { [admission.name]: key } },
+    };
+}
+function titleForToolName(name) {
+    return name.replace(/[-_]/g, ' ').replace(/\b\w/g, (char) => char.toUpperCase());
+}
+/** "AssetsController_getAll" → "assets_get-all", the name before tool-names.ts renames it. */
+export function derivedToolName(operationId) {
     const parts = operationId.split('_');
     if (parts.length < 2)
         return toKebab(operationId);
@@ -29,6 +131,10 @@ export function operationIdToToolName(operationId) {
     const method = toKebab(parts.slice(1).join('_'));
     return `${controller}_${method}`;
 }
+/** "AssetsController_getAll" → "assets_list". */
+export function operationIdToToolName(operationId) {
+    return currentToolName(derivedToolName(operationId));
+}
 function toKebab(str) {
     return str
         .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
@@ -124,7 +230,7 @@ function buildPath(pathTemplate, args) {
         if (value === undefined) {
             throw new Error(`Missing required path parameter: ${paramName}`);
         }
-        return encodeURIComponent(String(value));
+        return encodeURIComponent(parameterString(value));
     });
 }
 function buildQuery(parameters, args) {
@@ -135,11 +241,23 @@ function buildQuery(parameters, args) {
     for (const param of queryParams) {
         const value = args[param.name];
         if (value !== undefined && value !== null) {
-            query[param.name] = String(value);
+            query[param.name] = parameterString(value);
         }
     }
     return Object.keys(query).length > 0 ? query : undefined;
 }
+// Path and query values are JSON scalars or arrays such as `types`; keep String()'s
+// comma-joined array form and serialize plain objects instead of `[object Object]`.
+function parameterString(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' ||
+        typeof value === 'boolean' ||
+        typeof value === 'bigint' ||
+        Array.isArray(value))
+        return String(value);
+    return JSON.stringify(value);
+}
 function buildBody(operation, args) {
     if (!operation.requestBody)
         return undefined;

package/dist/tools/job-status.d.ts

@@ -0,0 +1,35 @@
+import { ApiRequestError } from '../http-client.js';
+/**
+ * One status vocabulary for every Sync job, so an agent waits on all of them the same way.
+ * Each kind's own read tool keeps returning its API status; jobs_get and jobs_wait add the
+ * unified one. docs/jobs.md has the full table.
+ */
+export declare const JOB_STATUSES: readonly ['PENDING', 'PROCESSING', 'COMPLETED', 'FAILED', 'REJECTED', 'CANCELED'];
+export type JobStatus = (typeof JOB_STATUSES)[number];
+export declare const JOB_KINDS: readonly ['generation', 'transcription', 'speaker_analysis', 'translation_preview', 'import', 'batch'];
+export type JobKind = (typeof JOB_KINDS)[number];
+export declare function isTerminal(status: JobStatus): boolean;
+/** The API's own status string on a job payload, if it has one. */
+export declare function rawStatus(payload: unknown): string | undefined;
+/**
+ * Maps a job payload's `status` to the unified status. A payload without a status counts
+ * as COMPLETED, as the per-kind waiters always did, so a wait never spins on a shape it
+ * cannot read; an unknown status counts as PROCESSING, so the wait keeps going until the
+ * budget runs out instead of reporting a result that may not exist.
+ */
+export declare function jobStatus(payload: unknown): JobStatus;
+/**
+ * Whether a wait should stop on this payload. A translation preview with recoveryRequired
+ * stays in its status, but polling will not resolve it: provider acceptance is uncertain
+ * and only Sync can recover it.
+ */
+export declare function jobSettled(payload: unknown): boolean;
+/** True for the 409 a social link import answers while it is still downloading. */
+export declare function isImportInProgress(error: unknown): error is ApiRequestError;
+/**
+ * The unified status for an error from a social link import, or undefined when the error
+ * did not come from the import (auth, the project-intent guard, the network) and should
+ * stay a tool error.
+ */
+export declare function importErrorStatus(error: unknown): JobStatus | undefined;
+//# sourceMappingURL=job-status.d.ts.map

package/dist/tools/job-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-status.d.ts","sourceRoot":"","sources":["../../src/tools/job-status.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,YAAY,YACvB,SAAS,EACT,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,UAAU,EACV,UAAU,CACF,CAAC;AACX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtD,eAAO,MAAM,SAAS,YACpB,YAAY,EACZ,eAAe,EACf,kBAAkB,EAClB,qBAAqB,EACrB,QAAQ,EACR,OAAO,CACC,CAAC;AACX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAIjD,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAErD;AAgBD,mEAAmE;AACnE,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI9D;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,CAMrD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAKpD;AAED,mFAAmF;AACnF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAI3E;AAWD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAKvE"}

package/dist/tools/job-status.js

@@ -0,0 +1,92 @@
+import { ApiRequestError } from '../http-client.js';
+/**
+ * One status vocabulary for every Sync job, so an agent waits on all of them the same way.
+ * Each kind's own read tool keeps returning its API status; jobs_get and jobs_wait add the
+ * unified one. docs/jobs.md has the full table.
+ */
+export const JOB_STATUSES = [
+    'PENDING',
+    'PROCESSING',
+    'COMPLETED',
+    'FAILED',
+    'REJECTED',
+    'CANCELED',
+];
+export const JOB_KINDS = [
+    'generation',
+    'transcription',
+    'speaker_analysis',
+    'translation_preview',
+    'import',
+    'batch',
+];
+const TERMINAL = new Set(['COMPLETED', 'FAILED', 'REJECTED', 'CANCELED']);
+export function isTerminal(status) {
+    return TERMINAL.has(status);
+}
+// API statuses that are not already a unified name. Case is ignored.
+const ALIASES = {
+    QUEUED: 'PENDING',
+    DOWNLOADING: 'PROCESSING',
+    // Translation previews attach their output after the provider finishes.
+    COMPLETING: 'PROCESSING',
+    // A batch has created its generations, or is writing its result file.
+    JOBS_CREATED: 'PROCESSING',
+    FINISHING: 'PROCESSING',
+    CANCELLED: 'CANCELED',
+    // Speaker analysis that cannot run for this source (no faces, too long, audio only).
+    UNAVAILABLE: 'FAILED',
+};
+/** The API's own status string on a job payload, if it has one. */
+export function rawStatus(payload) {
+    const status = payload && typeof payload === 'object' ? payload.status : undefined;
+    return typeof status === 'string' ? status : undefined;
+}
+/**
+ * Maps a job payload's `status` to the unified status. A payload without a status counts
+ * as COMPLETED, as the per-kind waiters always did, so a wait never spins on a shape it
+ * cannot read; an unknown status counts as PROCESSING, so the wait keeps going until the
+ * budget runs out instead of reporting a result that may not exist.
+ */
+export function jobStatus(payload) {
+    const raw = rawStatus(payload);
+    if (raw === undefined)
+        return 'COMPLETED';
+    const status = raw.trim().toUpperCase();
+    if (JOB_STATUSES.includes(status))
+        return status;
+    return ALIASES[status] ?? 'PROCESSING';
+}
+/**
+ * Whether a wait should stop on this payload. A translation preview with recoveryRequired
+ * stays in its status, but polling will not resolve it: provider acceptance is uncertain
+ * and only Sync can recover it.
+ */
+export function jobSettled(payload) {
+    return (isTerminal(jobStatus(payload)) ||
+        payload?.recoveryRequired === true);
+}
+/** True for the 409 a social link import answers while it is still downloading. */
+export function isImportInProgress(error) {
+    return (error instanceof ApiRequestError && error.status === 409 && error.code === 'import_in_progress');
+}
+// Import error codes from the API's ImportErrorCodes. Unlisted import_* codes are refusals.
+const IMPORT_ERROR_STATUS = {
+    import_failed: 'FAILED',
+    import_download_failed: 'FAILED',
+    import_upload_failed: 'FAILED',
+    import_processing_failed: 'FAILED',
+    import_cancelled_by_user: 'CANCELED',
+};
+/**
+ * The unified status for an error from a social link import, or undefined when the error
+ * did not come from the import (auth, the project-intent guard, the network) and should
+ * stay a tool error.
+ */
+export function importErrorStatus(error) {
+    if (!(error instanceof ApiRequestError) || !error.code?.startsWith('import_'))
+        return undefined;
+    if (error.status === 409 && error.code === 'import_in_progress')
+        return error.importDetails?.importStatus === 'queued' ? 'PENDING' : 'PROCESSING';
+    return IMPORT_ERROR_STATUS[error.code] ?? 'REJECTED';
+}

package/dist/tools/job-wait.d.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import type { ToolRequestContext } from './generator.js';
+/**
+ * Server-side waiting for the job tools. Agents otherwise write the same poll loop for
+ * every job type, and agent gateways pause servers that answer identical calls with
+ * identical "still running" results. One call with wait: true holds for up to
+ * WAIT_BUDGET_MS, sends progress notifications when the caller asked for them, and returns
+ * the latest state either way, so a still-running job just means calling again.
+ */
+export declare const WAIT_BUDGET_MS = 50000;
+export declare const waitInput: z.ZodOptional<z.ZodBoolean>;
+type Notify = (notification: {
+    method: 'notifications/progress';
+    params: {
+        progressToken: string | number;
+        progress: number;
+        message?: string;
+    };
+}) => Promise<void>;
+export declare function progressSender(token: unknown, notify: Notify): (progress: number, message?: string) => Promise<void>;
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * Read until done(state) or the budget runs out; returns the last state read.
+ * `describe` turns a state into the progress message; `delayMs` lets a pending
+ * state ask for a longer pause (an import's retryAfterMs).
+ *
+ * The budget bounds the whole call: no pause runs past it, and every read after
+ * the first gets a signal that aborts at the deadline, in which case the last
+ * state is returned. Only the caller's own cancellation is rethrown.
+ */
+export declare function pollUntil<T>(read: (signal?: AbortSignal) => Promise<T>, done: (state: T) => boolean, context: ToolRequestContext | undefined, options?: {
+    describe?: (state: T) => string;
+    delayMs?: (state: T) => number | undefined;
+    budgetMs?: number;
+    now?: () => number;
+}): Promise<T>;
+export declare const TIMED_OUT: unique symbol;
+/** Run `task` with a signal that also aborts after `ms`; a timeout yields TIMED_OUT. */
+export declare function boundedBy<T>(ms: number, caller: AbortSignal | undefined, task: (signal: AbortSignal) => Promise<T>): Promise<T | typeof TIMED_OUT>;
+export {};
+//# sourceMappingURL=job-wait.d.ts.map

package/dist/tools/job-wait.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-wait.d.ts","sourceRoot":"","sources":["../../src/tools/job-wait.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEzD;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,QAAS,CAAC;AAIrC,eAAO,MAAM,SAAS,6BAKnB,CAAC;AAEJ,KAAK,MAAM,GAAG,CAAC,YAAY,EAAE;IAC3B,MAAM,EAAE,wBAAwB,CAAC;IACjC,MAAM,EAAE;QAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAChF,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEpB,wBAAgB,cAAc,CAC5B,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,GACb,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAYvD;AAED,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAarE;AAED;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EAC1C,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,EAC3B,OAAO,EAAE,kBAAkB,GAAG,SAAS,EACvC,OAAO,GAAE;IACP,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC;IAChC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACf,GACL,OAAO,CAAC,CAAC,CAAC,CAgBZ;AAED,eAAO,MAAM,SAAS,eAAsB,CAAC;AAE7C,wFAAwF;AACxF,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,IAAI,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GACxC,OAAO,CAAC,CAAC,GAAG,OAAO,SAAS,CAAC,CAQ/B"}

package/dist/tools/job-wait.js

@@ -0,0 +1,84 @@
+import { z } from 'zod';
+/**
+ * Server-side waiting for the job tools. Agents otherwise write the same poll loop for
+ * every job type, and agent gateways pause servers that answer identical calls with
+ * identical "still running" results. One call with wait: true holds for up to
+ * WAIT_BUDGET_MS, sends progress notifications when the caller asked for them, and returns
+ * the latest state either way, so a still-running job just means calling again.
+ */
+export const WAIT_BUDGET_MS = 50_000;
+// Back off 1, 2, 4 then every 5 seconds, so quick jobs return quickly.
+const INTERVALS_MS = [1_000, 2_000, 4_000, 5_000];
+export const waitInput = z
+    .boolean()
+    .optional()
+    .describe('Wait on the server until the job finishes or about 50 seconds pass, then return its latest state. If it is still running, call again with wait: true instead of sleeping.');
+export function progressSender(token, notify) {
+    if (typeof token !== 'string' && typeof token !== 'number')
+        return async () => { };
+    let last = -1;
+    return async (progress, message) => {
+        // The spec requires progress to increase with every notification.
+        const value = Math.max(progress, last + 1e-6);
+        last = value;
+        await notify({
+            method: 'notifications/progress',
+            params: { progressToken: token, progress: value, ...(message ? { message } : {}) },
+        }).catch(() => { });
+    };
+}
+export function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(signal.reason);
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/**
+ * Read until done(state) or the budget runs out; returns the last state read.
+ * `describe` turns a state into the progress message; `delayMs` lets a pending
+ * state ask for a longer pause (an import's retryAfterMs).
+ *
+ * The budget bounds the whole call: no pause runs past it, and every read after
+ * the first gets a signal that aborts at the deadline, in which case the last
+ * state is returned. Only the caller's own cancellation is rethrown.
+ */
+export async function pollUntil(read, done, context, options = {}) {
+    const now = options.now ?? Date.now;
+    const deadline = now() + (options.budgetMs ?? WAIT_BUDGET_MS);
+    let state = await read(context?.signal);
+    for (let polls = 1; !done(state); polls++) {
+        await context?.progress?.(polls, options.describe?.(state));
+        const pause = options.delayMs?.(state) ?? INTERVALS_MS[Math.min(polls, INTERVALS_MS.length) - 1];
+        // Sleeping into the deadline only to return the same state helps nobody.
+        if (deadline - now() <= pause)
+            return state;
+        await sleep(pause, context?.signal);
+        const next = await boundedBy(deadline - now(), context?.signal, read);
+        if (next === TIMED_OUT)
+            return state;
+        state = next;
+    }
+    return state;
+}
+export const TIMED_OUT = Symbol('timed out');
+/** Run `task` with a signal that also aborts after `ms`; a timeout yields TIMED_OUT. */
+export async function boundedBy(ms, caller, task) {
+    const timeout = AbortSignal.timeout(Math.max(ms, 0));
+    try {
+        return await task(caller ? AbortSignal.any([caller, timeout]) : timeout);
+    }
+    catch (error) {
+        if (timeout.aborted && !caller?.aborted)
+            return TIMED_OUT;
+        throw error;
+    }
+}

package/dist/tools/jobs.d.ts

@@ -0,0 +1,3 @@
+import type { McpToolDefinition } from './generator.js';
+export declare function createJobTools(tools: McpToolDefinition[]): McpToolDefinition[];
+//# sourceMappingURL=jobs.d.ts.map

package/dist/tools/jobs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jobs.d.ts","sourceRoot":"","sources":["../../src/tools/jobs.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAsB,MAAM,gBAAgB,CAAC;AA8K5E,wBAAgB,cAAc,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,iBAAiB,EAAE,CA+F9E"}

package/dist/tools/jobs.js

@@ -0,0 +1,210 @@
+import { z } from 'zod';
+import { batchProgress } from './batches.js';
+import { attemptImport, importWaitOptions } from './generated-adapters.js';
+import { importErrorStatus, isTerminal, JOB_KINDS, JOB_STATUSES, jobStatus, } from './job-status.js';
+import { pollUntil } from './job-wait.js';
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** What the kind's own tool would show: its output schema's fields, when it has one. */
+function project(tool, payload) {
+    if (!isRecord(payload))
+        return { value: payload };
+    if (!tool.outputSchema)
+        return payload;
+    return Object.fromEntries(Object.keys(tool.outputSchema)
+        .filter((key) => key in payload)
+        .map((key) => [key, payload[key]]));
+}
+function percent(value) {
+    return typeof value === 'number' && Number.isFinite(value)
+        ? Math.min(Math.max(value, 0), 100)
+        : undefined;
+}
+const readJob = (args) => async (tool, input, context, signal) => {
+    const payload = await tool.handler(args(input), { ...context, signal });
+    return { status: jobStatus(payload), result: project(tool, payload) };
+};
+const KINDS = {
+    generation: {
+        tool: 'generations_get',
+        label: 'generation',
+        id: 'the generation id a create tool returned (lipsync_create, dubbing_create, lipsync_create-timeline, dialogue-videos_create)',
+        read: async (tool, input, context, signal) => {
+            // include=progress adds the worker's percent; the API's own long-poll would drop it.
+            const progressQuery = 'include' in tool.inputSchema ? { include: 'progress' } : {};
+            const payload = await tool.handler({ id: input.id, ...progressQuery }, { ...context, signal });
+            const raw = isRecord(payload) ? payload : {};
+            const progress = isRecord(raw.progress) ? raw.progress.percent : raw.progress_percent;
+            const estimate = isRecord(raw.generationEstimate) ? raw.generationEstimate : {};
+            const status = jobStatus(payload);
+            return {
+                status,
+                ...(percent(progress) === undefined || isTerminal(status)
+                    ? {}
+                    : { progress: percent(progress) }),
+                ...(typeof estimate.estimatedFinishAt === 'string' && !isTerminal(status)
+                    ? { estimatedFinishAt: estimate.estimatedFinishAt }
+                    : {}),
+                result: project(tool, payload),
+            };
+        },
+    },
+    transcription: {
+        tool: 'transcriptions_get',
+        label: 'transcription',
+        id: 'the transcription id (transcriptions_create or dialogue-transcriptions_create)',
+        read: readJob((input) => ({ id: input.id })),
+    },
+    speaker_analysis: {
+        tool: 'transcriptions_get-speaker-analysis',
+        label: 'speaker analysis',
+        id: 'the transcription id',
+        read: readJob((input) => ({ id: input.id })),
+    },
+    translation_preview: {
+        tool: 'translation-previews_get',
+        label: 'translation',
+        id: 'the translation-previews_create id, with its projectId',
+        read: readJob((input) => {
+            if (!input.projectId)
+                throw new Error('Pass the projectId of the translation preview.');
+            return { projectId: input.projectId, id: input.id };
+        }),
+    },
+    import: {
+        tool: 'assets_create',
+        label: 'import',
+        id: 'the social video link passed to assets_create, with the same projectId (and projectIntent, if that call needed it)',
+        read: async (tool, input, context, signal) => {
+            // Reading an import repeats the identical request; the API reuses the running import.
+            const args = {
+                url: input.id,
+                type: 'VIDEO',
+                ...(input.projectId === undefined ? {} : { projectId: input.projectId }),
+                ...(input.projectIntent === undefined ? {} : { projectIntent: input.projectIntent }),
+            };
+            try {
+                const attempt = await attemptImport(tool.handler, args, context, signal);
+                if ('asset' in attempt)
+                    return { status: 'COMPLETED', result: project(tool, attempt.asset) };
+                const { pending } = attempt;
+                const progress = percent(pending.importDetails?.progress);
+                return {
+                    status: importErrorStatus(pending) ?? 'PROCESSING',
+                    ...(progress === undefined ? {} : { progress }),
+                    retryAfterMs: importWaitOptions.delayMs(attempt),
+                    result: { code: pending.code, message: pending.message, ...pending.importDetails },
+                };
+            }
+            catch (error) {
+                const status = importErrorStatus(error);
+                if (!status)
+                    throw error;
+                const { message, status: httpStatus, code } = error;
+                return { status, result: { error: { message, status: httpStatus, code } } };
+            }
+        },
+    },
+    batch: {
+        tool: 'batches_get',
+        label: 'batch',
+        id: 'the batch id batches_create returned',
+        read: async (tool, input, context, signal) => {
+            const payload = await tool.handler({ id: input.id }, { ...context, signal });
+            const status = jobStatus(payload);
+            const progress = isRecord(payload) ? batchProgress(payload) : undefined;
+            return {
+                status,
+                ...(progress === undefined || isTerminal(status) ? {} : { progress }),
+                result: project(tool, payload),
+            };
+        },
+    },
+};
+const STATUS_HELP = 'status is one of PENDING, PROCESSING (still running: call jobs_wait again with the same input; never create the job again), COMPLETED, FAILED, REJECTED (the API refused it, such as an import limit or a moderation rejection) or CANCELED. result is what the kind’s own read tool returns, with its original status; a COMPLETED import’s result is the saved asset, whose id is the asset id. A finished batch’s result.results lists each item’s generation status and output. A translation_preview whose result.recoveryRequired is true has uncertain provider acceptance: do not create another job.';
+export function createJobTools(tools) {
+    const available = JOB_KINDS.flatMap((kind) => {
+        const tool = tools.find((candidate) => candidate.name === KINDS[kind].tool);
+        return tool && tool.resultFormat !== 'mcp' ? [{ kind, tool, spec: KINDS[kind] }] : [];
+    });
+    if (available.length === 0)
+        return [];
+    const kinds = available.map((entry) => entry.kind);
+    const input = z
+        .object({
+        kind: z.enum(kinds).describe('Which kind of job id is.'),
+        id: z.string().trim().min(1).describe('The job to read; see the tool description per kind.'),
+        projectId: z
+            .string()
+            .optional()
+            .describe('Required for translation_preview; for import, the project passed to assets_create.'),
+        projectIntent: z
+            .literal('explicit')
+            .optional()
+            .describe('import only: pass it when the assets_create call for this link needed it.'),
+    })
+        .strict();
+    const output = {
+        kind: z.enum(kinds),
+        id: z.string(),
+        status: z.enum(JOB_STATUSES).describe('The unified status; see the tool description.'),
+        progress: z
+            .number()
+            .min(0)
+            .max(100)
+            .optional()
+            .describe('Percent complete while running, when the API reports it.'),
+        estimatedFinishAt: z
+            .string()
+            .optional()
+            .describe('Server estimate (ISO 8601) of when a running job finishes, when the API has one.'),
+        retryAfterMs: z
+            .number()
+            .optional()
+            .describe('How long to wait before reading again, when the API asks for a pause.'),
+        result: z
+            .record(z.string(), z.unknown())
+            .describe('The job as the kind’s own read tool returns it.'),
+    };
+    const ids = available.map(({ kind, spec }) => `${kind}: ${spec.id}`).join('; ');
+    const read = async (args, context, signal = context?.signal) => {
+        const job = input.parse(args);
+        const entry = available.find((candidate) => candidate.kind === job.kind);
+        const reading = await entry.spec.read(entry.tool, job, context, signal);
+        return { kind: job.kind, id: job.id, ...reading };
+    };
+    // An import can start the download it reads, so neither tool is read-only.
+    const annotations = {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: kinds.includes('import'),
+    };
+    return [
+        {
+            name: 'jobs_get',
+            title: 'Read any Sync job',
+            description: `Read the current state of any Sync job once, by kind and id (${ids}). Returns {kind, id, status, progress?, estimatedFinishAt?, retryAfterMs?, result}. ${STATUS_HELP} To wait for a running job, use jobs_wait instead of calling this in a loop.`,
+            inputSchema: input.shape,
+            outputSchema: output,
+            annotations,
+            handler: (args, context) => read(args, context),
+        },
+        {
+            name: 'jobs_wait',
+            title: 'Wait for any Sync job',
+            description: `Wait on the server for any Sync job to finish, by kind and id (${ids}). Holds for up to about 50 seconds, sending progress notifications when the client asks for them, then returns the latest {kind, id, status, progress?, estimatedFinishAt?, retryAfterMs?, result}. ${STATUS_HELP}`,
+            inputSchema: input.shape,
+            outputSchema: output,
+            annotations,
+            handler: async (args, context) => {
+                const label = KINDS[input.parse(args).kind].label;
+                return pollUntil((signal) => read(args, context, signal), (job) => isTerminal(job.status) || job.result.recoveryRequired === true, context, {
+                    describe: (job) => `${label} ${job.status.toLowerCase()}${job.progress === undefined ? '' : ` ${Math.round(job.progress)}%`}`,
+                    delayMs: (job) => job.retryAfterMs,
+                });
+            },
+        },
+    ];
+}