@sync.so/mcp-server 0.1.4 → 0.2.0

package/dist/tools/dialogue.js

@@ -0,0 +1,309 @@
+import { z } from 'zod';
+import { ApiRequestError } from '../http-client.js';
+import { uploadRuntime } from '../upload-runtime.js';
+import { generationContextHeaders, generationContextSchema } from './generation-context.js';
+import { generateTools } from './generator.js';
+import { uploadMediaAsset } from './media-upload.js';
+import { modelOptionsSchema } from './model-options.js';
+import { generationOutputSchema } from './output-schemas.js';
+const paths = [
+    '/v2/transcriptions',
+    '/v2/transcriptions/{id}',
+    '/v2/dialogue-edits',
+    '/v2/dialogue-edits/{id}',
+];
+export function dialogueOperations(operations) {
+    return operations.filter((operation) => paths.includes(operation.path));
+}
+const sourceSchema = z.object({ projectId: z.uuid(), videoAssetId: z.uuid() });
+const object = z.record(z.string(), z.unknown());
+const previewKeySchema = z.string().regex(/^[A-Za-z0-9._~-]{1,128}$/);
+// The API's edit items are a oneOf, which the OpenAPI conversion turns into untyped items,
+// so agents had to guess their shape.
+const dialogueEdits = z
+    .array(z.discriminatedUnion('kind', [
+    z.object({
+        kind: z.literal('change'),
+        wordId: z.string().describe('Timed word ID from the source transcript.'),
+        replacement: z.string().min(1).max(500).describe('What the speaker says instead.'),
+        pronunciation: z
+            .string()
+            .min(1)
+            .max(100)
+            .optional()
+            .describe('Plain-text respelling for a name or word the voice would otherwise mispronounce.'),
+    }),
+    z.object({
+        kind: z.literal('remove'),
+        wordIds: z.array(z.string()).min(1).describe('Timed word IDs to remove.'),
+    }),
+]))
+    .min(1)
+    .max(100)
+    .describe('User-approved changes/removals referencing timed word IDs in the source transcript.');
+/** transcriptionJobId is the API's name; transcriptionId is the older MCP name. */
+function transcriptionJobId(args) {
+    const { transcriptionJobId: id, transcriptionId: alias } = args;
+    if (id && alias && id !== alias)
+        throw new Error('transcriptionJobId and transcriptionId name different transcriptions; pass transcriptionJobId only.');
+    return id ?? alias;
+}
+export function createDialogueTools(operations, httpClient) {
+    const selected = dialogueOperations(operations);
+    const tools = generateTools(selected, httpClient);
+    const find = (path, method) => tools[selected.findIndex((op) => op.path === path && op.method === method)];
+    const transcribe = find(paths[0], 'post');
+    const readTranscript = find(paths[1], 'get');
+    const preview = find(paths[2], 'post');
+    const readPreview = find(paths[3], 'get');
+    if (!transcribe || !readTranscript || !preview || !readPreview || !preview.inputSchema.edits)
+        return [];
+    const keyedPreview = selected.some((operation) => operation.path === paths[2] &&
+        operation.method === 'post' &&
+        operation.parameters.some((parameter) => parameter.in === 'header' && parameter.name.toLowerCase() === 'idempotency-key'));
+    async function source(args, signal) {
+        signal?.throwIfAborted();
+        const input = sourceSchema.parse(args);
+        const project = object.parse(await httpClient.request('get', `/v2/projects/${input.projectId}`, { signal }));
+        if (project.id !== input.projectId)
+            throw new Error('Could not verify project access.');
+        signal?.throwIfAborted();
+        const asset = z
+            .object({ id: z.uuid(), type: z.literal('VIDEO'), url: z.url(), name: z.string().nullish() })
+            .parse(await httpClient.request('get', `/v2/assets/${input.videoAssetId}`, { signal }));
+        if (asset.id !== input.videoAssetId)
+            throw new Error('Could not verify the source video.');
+        signal?.throwIfAborted();
+        return { ...input, sourceVideoUrl: asset.url, sourceName: asset.name ?? 'dialogue-source.mp4' };
+    }
+    async function copyToSyncStorage(input, signal) {
+        const assetId = await uploadMediaAsset(httpClient, 'video', {
+            download_url: input.sourceVideoUrl,
+            file_id: input.videoAssetId,
+            file_name: input.sourceName,
+        }, uploadRuntime, signal, { projectId: input.projectId, name: input.sourceName });
+        const asset = z
+            .object({ id: z.uuid(), type: z.literal('VIDEO'), url: z.url() })
+            .passthrough()
+            .parse(await httpClient.request('get', `/v2/assets/${assetId}`, { signal }));
+        if (asset.id !== assetId)
+            throw new Error('Could not verify the uploaded video.');
+        return asset;
+    }
+    async function checkedJob(tool, args, signal) {
+        const input = await source(args, signal);
+        const job = object.parse(await tool.handler({ id: z.uuid().parse(args.id) }, { signal }));
+        // URLs from the same API source must identify the same stored source. The
+        // generation API performs its own storage-object comparison before billing.
+        const sourceUrl = z.url().parse(job.sourceVideoUrl);
+        const a = new URL(sourceUrl);
+        const b = new URL(input.sourceVideoUrl);
+        if (a.origin !== b.origin || a.pathname !== b.pathname)
+            throw new Error('The job belongs to another source video.');
+        return job;
+    }
+    const readHints = { readOnlyHint: true, destructiveHint: false, openWorldHint: false };
+    const writeHints = {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
+    };
+    const generationSchema = sourceSchema.extend({
+        dialogueEditId: z.uuid(),
+        model: z.string().min(1),
+        options: modelOptionsSchema.optional(),
+    });
+    async function generationBody(args, signal) {
+        const input = generationSchema.parse(args);
+        await source(args, signal);
+        if (typeof input.options?.active_speaker_detection === 'boolean')
+            input.options.active_speaker_detection = {
+                auto_detect: input.options.active_speaker_detection,
+            };
+        return {
+            projectId: input.projectId,
+            model: input.model,
+            input: [{ type: 'video', assetId: input.videoAssetId }],
+            dialogueEdit: { id: input.dialogueEditId },
+            ...(input.options ? { options: input.options } : {}),
+        };
+    }
+    return [
+        {
+            name: 'dialogue_get-options',
+            title: 'Check Edit Dialogue availability',
+            description: 'Check whether the connected API supports timed-word Edit Dialogue. Does not transcribe, synthesize or generate.',
+            inputSchema: {},
+            annotations: readHints,
+            handler: async () => ({ available: true, keyedPreview, sourceUpload: true }),
+        },
+        {
+            name: 'dialogue_upload-source',
+            title: 'Copy a video for Edit Dialogue',
+            description: 'Copy an accessible saved video into Sync storage when transcription rejects its external source URL. Returns a new asset; use its id as videoAssetId for transcription, preview, and final video generation. Does not transcribe or spend generation credits.',
+            inputSchema: sourceSchema.shape,
+            outputSchema: {
+                asset: z.object({ id: z.uuid(), type: z.literal('VIDEO'), url: z.url() }).passthrough(),
+            },
+            annotations: writeHints,
+            handler: async (args, context) => ({
+                asset: await copyToSyncStorage(await source(args, context?.signal), context?.signal),
+            }),
+        },
+        {
+            name: 'dialogue-transcriptions_create',
+            title: 'Transcribe a video for Edit Dialogue',
+            description: 'Use this to start correcting or removing spoken words in a saved single-speaker video while keeping the original speaker voice. Transcribes timed words for Edit Dialogue; not whole-script replacement, translation, or choosing a different voice. Transcription is unbilled and identical sources reuse their existing job. A video outside Sync storage is copied there first; the result then carries the videoAssetId of that copy, which the rest of the workflow must use. Does not replace dialogue or generate a video.',
+            inputSchema: sourceSchema.shape,
+            annotations: writeHints,
+            handler: async (args, context) => {
+                const input = await source(args, context?.signal);
+                const start = (sourceVideoUrl) => transcribe.handler({ sourceVideoUrl, projectId: input.projectId, maxSourceSeconds: 600 }, context);
+                try {
+                    return await start(input.sourceVideoUrl);
+                }
+                catch (error) {
+                    // Agents rarely made the copy themselves after this rejection, so make it here.
+                    if (!(error instanceof ApiRequestError) ||
+                        error.status !== 422 ||
+                        !error.message.includes('must be hosted in sync. labs storage'))
+                        throw error;
+                    const copy = await copyToSyncStorage(input, context?.signal);
+                    try {
+                        return { ...object.parse(await start(copy.url)), videoAssetId: copy.id };
+                    }
+                    catch (retryError) {
+                        // Name the saved copy so a retry transcribes it instead of copying again.
+                        if (retryError instanceof Error)
+                            retryError.message += ` The video is saved in Sync storage as asset ${copy.id}; retry with videoAssetId ${copy.id}.`;
+                        throw retryError;
+                    }
+                }
+            },
+        },
+        {
+            name: 'dialogue-transcriptions_get',
+            title: 'Check an Edit Dialogue transcription',
+            description: 'Read the same transcription job until complete. Requires its original saved video and accessible project.',
+            inputSchema: sourceSchema.extend({ id: z.uuid() }).shape,
+            annotations: readHints,
+            handler: (args, context) => checkedJob(readTranscript, args, context?.signal),
+        },
+        {
+            name: 'dialogue-previews_create',
+            title: 'Preview dialogue edits',
+            description: 'Start an audio synthesis job for user-approved timed word changes/removals in a saved single-speaker video, preserving the original speaker voice. Requires a project, source video and completed transcription or prior preview accessible to the connected Sync account. May clone the source speaker voice and incur synthesis charges; confirm the edits and permission to use that voice before creating. Creates a saved preview without overwriting the source; does not generate the final video. Returns a preview job ID; poll dialogue-previews_get with the same project and source until completion, and disclose any failed edits on partial completion. Persist an idempotencyKey before creating when dialogue_get-options advertises keyedPreview. Recover only through an explicit retry of identical input with that same key; never retry an ambiguous creation automatically. Not for translation, choosing another voice, or arbitrary full-transcript replacement.',
+            inputSchema: sourceSchema.extend({
+                projectId: sourceSchema.shape.projectId.describe('Accessible Sync project for the preview. Keep unchanged on retries.'),
+                videoAssetId: sourceSchema.shape.videoAssetId.describe('Saved VIDEO asset for the transcription or prior preview, accessible to the connected account.'),
+                idempotencyKey: previewKeySchema
+                    .optional()
+                    .describe('Persist a unique key before creation when dialogue_get-options reports keyedPreview. Reuse only with identical inputs for an explicitly requested retry.'),
+                transcriptionJobId: z
+                    .uuid()
+                    .optional()
+                    .describe('Completed transcription ID for this source. Supply exactly one of transcriptionJobId or previousPreviewId.'),
+                previousPreviewId: z
+                    .uuid()
+                    .optional()
+                    .describe('Completed or partially completed preview ID for this source when reopening. Supply exactly one of previousPreviewId or transcriptionJobId.'),
+                edits: dialogueEdits,
+                transcriptionId: z
+                    .uuid()
+                    .optional()
+                    .describe('Deprecated alias of transcriptionJobId.')
+                    .meta({ deprecated: true }),
+            }).shape,
+            annotations: { ...writeHints, openWorldHint: false },
+            handler: async (args, context) => {
+                const key = previewKeySchema.optional().parse(args.idempotencyKey);
+                if (key && !keyedPreview)
+                    throw new Error('This API does not support keyed dialogue preview recovery.');
+                const transcriptionId = transcriptionJobId(args);
+                if (Boolean(transcriptionId) === Boolean(args.previousPreviewId)) {
+                    throw new Error('Provide one transcriptionJobId or previousPreviewId, not both.');
+                }
+                const input = await source(args, context?.signal);
+                const previous = args.previousPreviewId
+                    ? await checkedJob(readPreview, { ...args, id: args.previousPreviewId }, context?.signal)
+                    : undefined;
+                const transcriptJob = previous ??
+                    (await checkedJob(readTranscript, { ...args, id: transcriptionId }, context?.signal));
+                if (transcriptJob.status !== 'COMPLETED' &&
+                    !(previous && transcriptJob.status === 'COMPLETED_PARTIAL'))
+                    throw new Error('Wait for the source transcript to finish.');
+                const body = z.object(preview.inputSchema).parse({
+                    // Job snapshots retain the immutable source identity across rotating asset signatures.
+                    sourceVideoUrl: z.url().parse(transcriptJob.sourceVideoUrl),
+                    projectId: input.projectId,
+                    transcript: previous ? previous.sourceTranscript : transcriptJob.transcript,
+                    edits: args.edits,
+                    ...(previous?.voiceId ? { voiceId: previous.voiceId } : {}),
+                    ...(previous ? {} : { transcriptionJobId: transcriptionId }),
+                    ...(previous && JSON.stringify(previous.edits) === JSON.stringify(args.edits)
+                        ? { rerunOfJobId: previous.id }
+                        : {}),
+                });
+                return httpClient.request('post', paths[2], {
+                    body,
+                    ...(key ? { headers: { 'Idempotency-Key': key } } : {}),
+                    signal: context?.signal,
+                });
+            },
+        },
+        {
+            name: 'dialogue-previews_get',
+            title: 'Check a dialogue edit preview',
+            description: 'Read one existing Edit Dialogue audio preview. Partial completion must be disclosed, not described as every edit succeeding.',
+            inputSchema: sourceSchema.extend({ id: z.uuid() }).shape,
+            annotations: readHints,
+            handler: (args, context) => checkedJob(readPreview, args, context?.signal),
+        },
+        {
+            name: 'dialogue-videos_estimate',
+            title: 'Estimate an edited dialogue video',
+            description: 'Estimate final video cost using the completed dialogue preview and canonical server retiming. Does not generate or reserve credits.',
+            inputSchema: generationSchema.shape,
+            annotations: readHints,
+            handler: async (args, context) => httpClient.request('post', '/v2/analyze/cost', {
+                body: await generationBody(args, context?.signal),
+                signal: context?.signal,
+            }),
+        },
+        {
+            name: 'dialogue-videos_create',
+            title: 'Create the edited dialogue video',
+            description: 'Create a new lip-synced video from a saved single-speaker video and its completed, user-approved Edit Dialogue audio preview. Use this to render targeted corrections or removals of spoken words while preserving the original speaker voice. Not for translation, whole-script replacement, or choosing a different voice. ' +
+                "This is a paid action that starts a generation job and consumes Sync credits. First use dialogue-videos_estimate with the same source, preview and model, then obtain the user's approval of the preview, configuration and estimated cost. Requires a project and source video accessible to the connected account, and a completed dialogue preview for that same source. Creates a new output without overwriting the source video. " +
+                'Returns a generation ID, not a finished video. Poll generations_get with that ID until completion. Persist one idempotency key for the approved request; on an uncertain response, reuse that key with identical inputs instead of starting a second paid job.',
+            inputSchema: generationSchema.extend({
+                projectId: sourceSchema.shape.projectId.describe('Accessible Sync project for the new output. Keep unchanged on retries.'),
+                videoAssetId: sourceSchema.shape.videoAssetId.describe('Saved VIDEO asset used for the approved dialogue preview, accessible to the connected account.'),
+                dialogueEditId: generationSchema.shape.dialogueEditId.describe('Completed Edit Dialogue audio preview ID for this source video and the current user-approved edits. Not a transcription or generation ID.'),
+                model: generationSchema.shape.model.describe('Lip-sync model returned by models_list, matching the approved estimate.'),
+                continuation: generationContextSchema
+                    .optional()
+                    .describe('Only for an explicitly requested continuation of an existing generation in this project. The workflow must be edit_dialogue.'),
+                idempotencyKey: z
+                    .string()
+                    .regex(/^[A-Za-z0-9._~-]{1,128}$/)
+                    .describe('Persist one unique key per approved generation. Reuse the exact key and unchanged inputs when recovering an uncertain response; never automatically generate a replacement key.'),
+            }).shape,
+            outputSchema: generationOutputSchema,
+            annotations: { ...writeHints, openWorldHint: false },
+            handler: async (args, context) => {
+                const key = z
+                    .string()
+                    .regex(/^[A-Za-z0-9._~-]{1,128}$/)
+                    .parse(args.idempotencyKey);
+                const lineage = await generationContextHeaders(httpClient, args, ['edit_dialogue'], context?.signal);
+                return httpClient.request('post', '/v2/generate', {
+                    body: await generationBody(args, context?.signal),
+                    headers: { ...lineage, 'Idempotency-Key': key },
+                    signal: context?.signal,
+                });
+            },
+        },
+    ];
+}

package/dist/tools/estimate-duration.d.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+export declare const estimateDurationInputs: {
+    script: z.ZodOptional<z.ZodString>;
+    audioDuration: z.ZodOptional<z.ZodNumber>;
+    visualType: z.ZodOptional<z.ZodEnum<{
+        image: "image";
+        video: "video";
+    }>>;
+    videoDuration: z.ZodOptional<z.ZodNumber>;
+    syncMode: z.ZodOptional<z.ZodEnum<{
+        bounce: "bounce";
+        cut_off: "cut_off";
+        loop: "loop";
+        remap: "remap";
+        silence: "silence";
+    }>>;
+};
+export declare function resolveEstimateDuration(args: Record<string, unknown>): {
+    args: {
+        [x: string]: unknown;
+    };
+    durationEstimate: undefined;
+} | {
+    args: {
+        duration: number;
+    };
+    durationEstimate: {
+        durationSeconds: number;
+        audioDurationSeconds: number;
+        source: string;
+        approximate: boolean;
+        excludesSpeechSynthesis: boolean;
+    };
+};
+//# sourceMappingURL=estimate-duration.d.ts.map

package/dist/tools/estimate-duration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"estimate-duration.d.ts","sourceRoot":"","sources":["../../src/tools/estimate-duration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAWxB,eAAO,MAAM,sBAAsB;IACjC,MAAM;IAGN,aAAa;IAGb,UAAU;;;;IAGV,aAAa;IAGb,QAAQ;;;;;;;CAGT,CAAC;AAkBF,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;;;;;;;;;;;;EA6CpE"}

package/dist/tools/estimate-duration.js

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+const positiveSeconds = z.number().finite().positive();
+const contextSchema = z.object({
+    script: z.string().trim().min(1).max(5000).optional(),
+    audioDuration: positiveSeconds.optional(),
+    visualType: z.enum(['image', 'video']).optional(),
+    videoDuration: positiveSeconds.optional(),
+    syncMode: z.enum(['bounce', 'loop', 'cut_off', 'silence', 'remap']).optional(),
+});
+export const estimateDurationInputs = {
+    script: contextSchema.shape.script.describe('Replacement speech text. Estimates spoken duration without synthesizing audio. Use for script-driven lipsync instead of pricing the full source video. An approximate quote; final speech length may differ.'),
+    audioDuration: contextSchema.shape.audioDuration.describe('Measured replacement audio duration in seconds. Prefer this over a script estimate once speech audio exists.'),
+    visualType: contextSchema.shape.visualType.describe('Visual input type. Set image for image-to-video quotes; images always follow speech duration, including with cut_off or silence. Videos require videoDuration for those modes.'),
+    videoDuration: contextSchema.shape.videoDuration.describe('Source video duration in seconds, used with syncMode to account for cut_off or silence. Omit for an image.'),
+    syncMode: contextSchema.shape.syncMode.describe('The same sync_mode selected for generation. For videos, cut_off uses the shorter input and silence the longer input. Images and other modes follow replacement audio duration.'),
+};
+// Match Sync's @sync/common/tts estimateAudioDuration. This standalone service
+// cannot import the API monorepo's workspace packages.
+function scriptDuration(script) {
+    let words = 0;
+    for (const segment of new Intl.Segmenter(undefined, { granularity: 'word' }).segment(script)) {
+        if (!segment.isWordLike)
+            continue;
+        const cjkCharacters = segment.segment.match(/[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}]/gu)?.length ??
+            0;
+        words += Math.max(1, cjkCharacters);
+    }
+    const characters = script.match(/[\p{L}\p{N}]/gu)?.length ?? 0;
+    const wordDuration = words <= 1 ? words : Math.max(1, (words / 160) * 60);
+    return Number(Math.max(wordDuration, characters / 16).toFixed(2));
+}
+export function resolveEstimateDuration(args) {
+    const { script, audioDuration, visualType, videoDuration, syncMode } = contextSchema.parse(args);
+    const { script: _script, audioDuration: _audio, visualType: _visualType, videoDuration: _video, syncMode: _mode, ...body } = args;
+    if (script === undefined && audioDuration === undefined) {
+        if (videoDuration !== undefined || syncMode !== undefined)
+            throw new Error('Supply script or audioDuration when using videoDuration or syncMode.');
+        return { args: body, durationEstimate: undefined };
+    }
+    if (args.workflow === 'translate-and-dub')
+        throw new Error('Translation estimates use source duration, not replacement script or audio.');
+    if (visualType === 'image' && videoDuration !== undefined)
+        throw new Error('Omit videoDuration for an image input.');
+    if (visualType !== 'image' &&
+        (syncMode === 'cut_off' || syncMode === 'silence') &&
+        videoDuration === undefined)
+        throw new Error('Supply videoDuration to estimate cut_off or silence accurately.');
+    const driverDuration = positiveSeconds.parse(audioDuration ?? scriptDuration(script ?? ''));
+    const duration = videoDuration === undefined
+        ? driverDuration
+        : syncMode === 'cut_off'
+            ? Math.min(driverDuration, videoDuration)
+            : syncMode === 'silence'
+                ? Math.max(driverDuration, videoDuration)
+                : driverDuration;
+    return {
+        args: { ...body, duration },
+        durationEstimate: {
+            durationSeconds: duration,
+            audioDurationSeconds: driverDuration,
+            source: audioDuration === undefined ? 'script' : 'audio',
+            approximate: audioDuration === undefined,
+            excludesSpeechSynthesis: true,
+        },
+    };
+}

package/dist/tools/feedback.d.ts

@@ -0,0 +1,14 @@
+import type { HttpClient } from '../http-client.js';
+import type { ParsedOperation } from '../openapi/types.js';
+import type { McpToolDefinition } from './generator.js';
+/**
+ * Agents hit friction no one sees: an error that does not say what to fix, a workflow
+ * that needs a workaround, a missing tool. feedback_send lets them report it to the team
+ * as it happens, through the API's POST /v2/feedback (captured for daily triage). The tool
+ * exists only when the connected API publishes that operation.
+ */
+export declare const FEEDBACK_OPERATION_ID = "agentFeedback_submit";
+export declare function feedbackOperation(operation: ParsedOperation): boolean;
+export declare function createFeedbackTools(operations: ParsedOperation[], http: HttpClient, version: string): McpToolDefinition[];
+export declare const FEEDBACK_INSTRUCTIONS = "When feedback_send is available and a Sync tool error does not say what to fix, a result is wrong, or you need a workaround or a missing capability, finish or stop the task as you normally would, then call feedback_send once for that problem with the tool, the exact error and what would have helped. ";
+//# sourceMappingURL=feedback.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"feedback.d.ts","sourceRoot":"","sources":["../../src/tools/feedback.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,yBAAyB,CAAC;AAE5D,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,eAAe,GAAG,OAAO,CAMrE;AAsCD,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,eAAe,EAAE,EAC7B,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,MAAM,GACd,iBAAiB,EAAE,CAmCrB;AAED,eAAO,MAAM,qBAAqB,kTAC+Q,CAAC"}

package/dist/tools/feedback.js

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+/**
+ * Agents hit friction no one sees: an error that does not say what to fix, a workflow
+ * that needs a workaround, a missing tool. feedback_send lets them report it to the team
+ * as it happens, through the API's POST /v2/feedback (captured for daily triage). The tool
+ * exists only when the connected API publishes that operation.
+ */
+export const FEEDBACK_OPERATION_ID = 'agentFeedback_submit';
+export function feedbackOperation(operation) {
+    return (operation.operationId === FEEDBACK_OPERATION_ID &&
+        operation.method === 'post' &&
+        operation.path === '/v2/feedback');
+}
+const input = z
+    .object({
+    kind: z
+        .enum(['confusing_error', 'bug', 'missing_capability', 'workaround', 'docs', 'other'])
+        .describe('confusing_error: an error that did not say what to fix. bug: wrong result or crash. missing_capability: a tool or option you needed. workaround: you had to do extra steps. docs: a description that misled you.'),
+    message: z
+        .string()
+        .trim()
+        .min(1)
+        .max(4000)
+        .describe('What you tried, what happened, and what would have helped. Include the exact error text. No personal data or secrets.'),
+    tool: z.string().trim().min(1).max(128).optional().describe('Tool the feedback is about.'),
+    errorCode: z.string().trim().min(1).max(128).optional().describe('Error code you received.'),
+    generationId: z.uuid().optional().describe('Generation the feedback is about.'),
+    jobId: z
+        .string()
+        .trim()
+        .min(1)
+        .max(128)
+        .optional()
+        .describe('Other job the feedback is about: an import, transcription or translation id.'),
+    severity: z
+        .enum(['blocker', 'major', 'minor'])
+        .optional()
+        .describe('blocker: you could not finish. major: you finished with a workaround. minor: an annoyance.'),
+})
+    .strict();
+const receipt = z.object({ id: z.string(), received: z.literal(true) });
+export function createFeedbackTools(operations, http, version) {
+    if (!operations.some(feedbackOperation))
+        return [];
+    return [
+        {
+            name: 'feedback_send',
+            title: 'Send feedback to Sync',
+            description: 'Tell the Sync team about friction with these tools: an error that did not say what to fix, a result that was wrong, a capability you needed, or extra steps you had to take. Send one report per problem, after you have dealt with it; the team reviews reports daily. Does not change, retry or cancel any job, and never needs the user’s approval.',
+            inputSchema: input.shape,
+            outputSchema: receipt.shape,
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: false,
+                openWorldHint: false,
+            },
+            handler: async (args, context) => receipt.parse(await http.request('post', '/v2/feedback', {
+                body: {
+                    ...input.parse(args),
+                    source: 'mcp',
+                    mcpVersion: version,
+                    client: {
+                        name: (context?.clientName ?? context?.clientProfile?.name ?? 'unknown').slice(0, 128),
+                    },
+                },
+                signal: context?.signal,
+            })),
+        },
+    ];
+}
+export const FEEDBACK_INSTRUCTIONS = 'When feedback_send is available and a Sync tool error does not say what to fix, a result is wrong, or you need a workaround or a missing capability, finish or stop the task as you normally would, then call feedback_send once for that problem with the tool, the exact error and what would have helped. ';

package/dist/tools/generated-adapters.d.ts

@@ -0,0 +1,25 @@
+import type { ApiRequestError, HttpClient } from '../http-client.js';
+import type { ParsedOperation } from '../openapi/types.js';
+import type { McpToolDefinition, ToolRequestContext } from './generator.js';
+/**
+ * Agent-facing fixes for tools generated straight from the public OpenAPI spec. Each one
+ * keeps accepting the generated input, so callers holding the old tool list still work.
+ */
+export declare const projectTargetTools: WeakSet<McpToolDefinition>;
+type JsonTool = Exclude<McpToolDefinition, {
+    resultFormat: 'mcp';
+}>;
+/** One import attempt: the saved asset, or the 409 that says it is still downloading. */
+type ImportAttempt = {
+    asset: unknown;
+} | {
+    pending: ApiRequestError;
+};
+export declare function attemptImport(handler: JsonTool['handler'], args: Record<string, unknown>, context: ToolRequestContext | undefined, signal?: AbortSignal | undefined): Promise<ImportAttempt>;
+export declare const importWaitOptions: {
+    describe: (attempt: ImportAttempt) => string;
+    delayMs: (attempt: ImportAttempt) => number | undefined;
+};
+export declare function adaptGeneratedTool(tool: McpToolDefinition, operation: ParsedOperation | undefined, http: HttpClient): McpToolDefinition;
+export {};
+//# sourceMappingURL=generated-adapters.d.ts.map

package/dist/tools/generated-adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated-adapters.d.ts","sourceRoot":"","sources":["../../src/tools/generated-adapters.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAI5E;;;GAGG;AAIH,eAAO,MAAM,kBAAkB,4BAAmC,CAAC;AAKnE,KAAK,QAAQ,GAAG,OAAO,CAAC,iBAAiB,EAAE;IAAE,YAAY,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC;AAwFpE,yFAAyF;AACzF,KAAK,aAAa,GAAG;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,eAAe,CAAA;CAAE,CAAC;AAEvE,wBAAsB,aAAa,CACjC,OAAO,EAAE,QAAQ,CAAC,SAAS,CAAC,EAC5B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,kBAAkB,GAAG,SAAS,EACvC,MAAM,0BAAkB,GACvB,OAAO,CAAC,aAAa,CAAC,CAOxB;AAED,eAAO,MAAM,iBAAiB;IAC5B,QAAQ,YAAY,aAAa;IAIjC,OAAO,YAAY,aAAa;CAEjC,CAAC;AAuBF,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,iBAAiB,EACvB,SAAS,EAAE,eAAe,GAAG,SAAS,EACtC,IAAI,EAAE,UAAU,GACf,iBAAiB,CAWnB"}