@sync.so/mcp-server 0.1.4 → 0.2.0

package/dist/tools/media-upload.d.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import type { HttpClient } from '../http-client.js';
+import type { UploadRuntime } from '../upload-runtime.js';
+export declare const fileInput: z.ZodObject<{
+    download_url: z.ZodString;
+    file_id: z.ZodString;
+    mime_type: z.ZodOptional<z.ZodString>;
+    file_name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type FileInput = z.infer<typeof fileInput>;
+export type MediaKind = 'video' | 'image' | 'audio';
+type ResolvedMedia = {
+    type: MediaKind;
+    url?: string;
+    assetId?: string;
+};
+export declare const ASSET_TYPE_BY_KIND: Record<MediaKind, 'VIDEO' | 'IMAGE' | 'AUDIO'>;
+export declare function mediaContentType(kind: MediaKind, ...declared: Array<string | null | undefined>): string;
+export type MediaParam = string | FileInput | undefined;
+export declare function assertValidFileParam(kind: MediaKind, fileParam: MediaParam): asserts fileParam is FileInput | undefined;
+export declare function uploadMediaAsset(httpClient: HttpClient, kind: MediaKind, fileParam: FileInput, runtime: UploadRuntime, signal?: AbortSignal, assetDetails?: {
+    projectId?: string;
+    name?: string;
+}): Promise<string>;
+export declare function resolveMedia(httpClient: HttpClient, kind: MediaKind, urlParam: string | undefined, assetIdParam: string | undefined, fileParam: MediaParam, runtime: UploadRuntime, signal?: AbortSignal): Promise<ResolvedMedia>;
+export {};
+//# sourceMappingURL=media-upload.d.ts.map

package/dist/tools/media-upload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-upload.d.ts","sourceRoot":"","sources":["../../src/tools/media-upload.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAI1D,eAAO,MAAM,SAAS;;;;;iBAKpB,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAClD,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;AACpD,KAAK,aAAa,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzE,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAI7E,CAAC;AAUF,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,SAAS,EACf,GAAG,QAAQ,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,GAC5C,MAAM,CAMR;AA2ND,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;AAExD,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,SAAS,EACf,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC,SAAS,IAAI,SAAS,GAAG,SAAS,CAQ5C;AAED,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,SAAS,EACf,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,aAAa,EACtB,MAAM,CAAC,EAAE,WAAW,EACpB,YAAY,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GACvD,OAAO,CAAC,MAAM,CAAC,CAMjB;AAED,wBAAsB,YAAY,CAChC,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,SAAS,EAAE,UAAU,EACrB,OAAO,EAAE,aAAa,EACtB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CAkBxB"}

package/dist/tools/media-upload.js

@@ -0,0 +1,247 @@
+import { createReadStream, createWriteStream } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Readable, Transform } from 'node:stream';
+import { finished, pipeline } from 'node:stream/promises';
+import { z } from 'zod';
+import { createUploadSourceDispatcher, validatedUploadSourceUrl } from '../upload-source.js';
+// A file as ChatGPT delivers it for an `openai/fileParams` field.
+export const fileInput = z.object({
+    download_url: z.string(),
+    file_id: z.string(),
+    mime_type: z.string().optional(),
+    file_name: z.string().optional(),
+});
+export const ASSET_TYPE_BY_KIND = {
+    video: 'VIDEO',
+    image: 'IMAGE',
+    audio: 'AUDIO',
+};
+const DEFAULT_CONTENT_TYPE = {
+    video: 'video/mp4',
+    image: 'image/png',
+    audio: 'audio/mpeg',
+};
+// ChatGPT file links often answer with a generic type such as application/octet-stream,
+// which Sync storage rejects, so use the first declared type of the expected kind.
+export function mediaContentType(kind, ...declared) {
+    for (const value of declared) {
+        const type = value?.split(';')[0]?.trim().toLowerCase();
+        if (type?.startsWith(`${kind}/`))
+            return type;
+    }
+    return DEFAULT_CONTENT_TYPE[kind];
+}
+// The host of a URL, for error messages — so a failure says *where* it tried to
+// reach, not just "fetch failed".
+function hostOf(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return 'invalid-url';
+    }
+}
+// Node's fetch throws `TypeError: fetch failed` and hides the real reason (DNS,
+// TLS, connection refused, unsupported protocol) on `.cause`. Surface it.
+function reason(err) {
+    if (err instanceof Error) {
+        const cause = err.cause;
+        if (cause instanceof Error && cause.message)
+            return `${err.message} — ${cause.message}`;
+        return err.message;
+    }
+    return String(err);
+}
+async function cancelResponseBody(response) {
+    try {
+        await response.body?.cancel();
+    }
+    catch {
+        // Preserve the actionable validation or upstream error that caused cancellation.
+    }
+}
+function validatedUploadUrl(file, kind) {
+    const src = file.download_url;
+    if (!src) {
+        throw new Error(`The uploaded ${kind} is missing its download_url.`);
+    }
+    if (!/^https?:\/\//i.test(src)) {
+        throw new Error(`The uploaded ${kind} isn't a fetchable URL (received "${src.slice(0, 80)}"). ` +
+            `Pass a public ${kind} URL via ${kind}Url instead.`);
+    }
+    return validatedUploadSourceUrl(src);
+}
+/**
+ * Copy a media file into Sync storage and return its durable assetId.
+ *
+ * ChatGPT hands an uploaded file to the tool as a short-lived `download_url`
+ * (it is only valid while this tool call is being handled). A Sync generation,
+ * though, fetches its input media asynchronously on the worker — long after
+ * this call returns — by which point the ChatGPT URL is dead. So we pull the
+ * bytes now and re-host them through the assets pipeline; the returned assetId
+ * resolves to a durable Sync URL at submit time and survives the job queue.
+ *
+ * Each hop throws a distinct, host-tagged error: the three external steps
+ * (download from ChatGPT, PUT to Sync storage, register) fail in different ways
+ * and a bare "fetch failed" can't be acted on — by the model or by us.
+ */
+async function rehostUpload(httpClient, file, kind, runtime, signal, assetDetails = {}) {
+    // A real upload is an http(s) URL we can fetch. A sandbox/local reference
+    // (e.g. "sandbox:/mnt/data/...") can't be re-hosted — tell the caller to pass
+    // a public URL instead, and echo the value so the cause is visible.
+    signal.throwIfAborted();
+    const src = validatedUploadUrl(file, kind);
+    const dispatcher = createUploadSourceDispatcher(signal);
+    let download;
+    let tempDirectory;
+    let tempPath;
+    let uploadBody;
+    let put;
+    let downloadPipelineStarted = false;
+    let actualSize = 0;
+    try {
+        // 1. Download the source through the public-destination guard.
+        try {
+            download = await fetch(src, { signal, dispatcher, redirect: 'error' });
+        }
+        catch (err) {
+            if (signal.aborted)
+                throw signal.reason;
+            throw new Error(`Could not reach the uploaded ${kind} at ${hostOf(src)}: ${reason(err)}.`, {
+                cause: err,
+            });
+        }
+        if (!download.ok) {
+            await cancelResponseBody(download);
+            throw new Error(`The uploaded ${kind} URL returned HTTP ${download.status}.`);
+        }
+        const contentType = mediaContentType(kind, download.headers.get('content-type'), file.mime_type);
+        const fileName = file.file_name ?? `chatgpt-upload-${kind}`;
+        const declaredSizeHeader = download.headers.get('content-length');
+        const declaredSize = declaredSizeHeader === null ? undefined : Number(declaredSizeHeader);
+        const encodings = (download.headers.get('content-encoding') ?? '')
+            .split(',')
+            .map((encoding) => encoding.trim().toLowerCase());
+        const compressedEncodings = new Set(['gzip', 'x-gzip', 'deflate', 'br', 'zstd']);
+        const hasEncodedBody = encodings.some((encoding) => compressedEncodings.has(encoding));
+        if (declaredSize !== undefined && (!Number.isSafeInteger(declaredSize) || declaredSize < 0)) {
+            await cancelResponseBody(download);
+            throw new Error(`The uploaded ${kind} has an invalid Content-Length header.`);
+        }
+        if (declaredSize !== undefined && declaredSize > runtime.config.maxBytes) {
+            await cancelResponseBody(download);
+            throw new Error(`The uploaded ${kind} is too large (${declaredSize} bytes; limit ${runtime.config.maxBytes} bytes).`);
+        }
+        if (!download.body) {
+            await cancelResponseBody(download);
+            throw new Error(`The uploaded ${kind} response did not include a body.`);
+        }
+        tempDirectory = await mkdtemp(join(tmpdir(), 'sync-mcp-upload-'));
+        tempPath = join(tempDirectory, 'upload');
+        const validateSize = new Transform({
+            transform(chunk, _encoding, callback) {
+                actualSize += chunk.byteLength;
+                runtime.recordDownloadedBytes(chunk.byteLength);
+                if (actualSize > runtime.config.maxBytes) {
+                    callback(new Error(`The uploaded ${kind} is too large (limit ${runtime.config.maxBytes} bytes).`));
+                    return;
+                }
+                callback(null, chunk);
+            },
+        });
+        downloadPipelineStarted = true;
+        await pipeline(Readable.fromWeb(download.body), validateSize, createWriteStream(tempPath, { flags: 'wx' }), { signal });
+        if (declaredSize !== undefined && !hasEncodedBody && actualSize !== declaredSize) {
+            throw new Error(`The uploaded ${kind} size did not match Content-Length (expected ${declaredSize}, received ${actualSize}).`);
+        }
+        // 2. Ask Sync for a presigned upload URL after the bounded stream has been measured.
+        signal.throwIfAborted();
+        const { uploadUrl, url } = (await httpClient.request('post', '/v2/assets/upload', {
+            body: { fileName, contentType, size: actualSize },
+            signal,
+        }));
+        // 3. Upload from disk so large and unknown-length inputs never occupy one large buffer.
+        signal.throwIfAborted();
+        uploadBody = createReadStream(tempPath);
+        try {
+            put = await fetch(uploadUrl, {
+                method: 'PUT',
+                headers: { 'Content-Type': contentType, 'Content-Length': String(actualSize) },
+                body: uploadBody,
+                duplex: 'half',
+                // Redirect replay tees the stream and retains a full upload in memory.
+                redirect: 'error',
+                signal,
+            });
+        }
+        catch (err) {
+            uploadBody.destroy();
+            throw new Error(`Could not upload the ${kind} to Sync storage at ${hostOf(uploadUrl)}: ${reason(err)}.`, { cause: err });
+        }
+        if (!put.ok) {
+            throw new Error(`Sync storage rejected the ${kind} upload (HTTP ${put.status}).`);
+        }
+        await finished(uploadBody, { signal });
+        runtime.recordUploadedBytes(actualSize);
+        // 4. Register the uploaded object as an asset.
+        signal.throwIfAborted();
+        const asset = (await httpClient.request('post', '/v2/assets', {
+            body: { url, type: ASSET_TYPE_BY_KIND[kind], ...assetDetails },
+            signal,
+        }));
+        return asset.id;
+    }
+    catch (error) {
+        if (signal.aborted)
+            throw signal.reason;
+        throw error;
+    }
+    finally {
+        uploadBody?.destroy();
+        if (put)
+            await cancelResponseBody(put);
+        if (download && !downloadPipelineStarted)
+            await cancelResponseBody(download);
+        await dispatcher.destroy().catch(() => runtime.recordCleanupFailure());
+        if (tempDirectory) {
+            try {
+                await rm(tempDirectory, { recursive: true, force: true });
+            }
+            catch {
+                // Cleanup must not replace a durable asset ID or the primary upload error.
+                // Count failures without exposing local paths or sensitive error details.
+                runtime.recordCleanupFailure();
+            }
+        }
+    }
+}
+export function assertValidFileParam(kind, fileParam) {
+    if (typeof fileParam === 'string') {
+        throw new Error(`Got a string in the ${kind} file slot ("${fileParam.slice(0, 80)}"). ` +
+            `Pass public URLs via ${kind}Url instead; file slots must be ChatGPT file objects.`);
+    }
+    if (fileParam)
+        validatedUploadUrl(fileParam, kind);
+}
+export async function uploadMediaAsset(httpClient, kind, fileParam, runtime, signal, assetDetails = {}) {
+    return runtime.run((uploadSignal) => rehostUpload(httpClient, fileParam, kind, runtime, uploadSignal, assetDetails), { signal });
+}
+export async function resolveMedia(httpClient, kind, urlParam, assetIdParam, fileParam, runtime, signal) {
+    signal?.throwIfAborted();
+    if (assetIdParam)
+        return { type: kind, assetId: assetIdParam };
+    // An explicit URL the model already holds (tts output, public/asset URL) wins.
+    if (urlParam)
+        return { type: kind, url: urlParam };
+    assertValidFileParam(kind, fileParam);
+    if (fileParam) {
+        return {
+            type: kind,
+            assetId: await uploadMediaAsset(httpClient, kind, fileParam, runtime, signal),
+        };
+    }
+    // Unreachable — callers validate presence first.
+    throw new Error(`No ${kind} provided.`);
+}

package/dist/tools/model-options.d.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+export declare const modelOptionsSchema: z.ZodObject<{
+    sync_mode: z.ZodOptional<z.ZodEnum<{
+        bounce: "bounce";
+        cut_off: "cut_off";
+        loop: "loop";
+        remap: "remap";
+        silence: "silence";
+    }>>;
+    temperature: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    active_speaker_detection: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+        auto_detect: z.ZodOptional<z.ZodBoolean>;
+        use_v2: z.ZodOptional<z.ZodBoolean>;
+        v3: z.ZodOptional<z.ZodBoolean>;
+        face_image: z.ZodOptional<z.ZodString>;
+        frame_number: z.ZodOptional<z.ZodNumber>;
+        coordinates: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+    }, z.core.$strict>]>>;
+    occlusion_detection_enabled: z.ZodOptional<z.ZodBoolean>;
+    reasoning_enabled: z.ZodOptional<z.ZodBoolean>;
+    model_mode: z.ZodOptional<z.ZodEnum<{
+        face: "face";
+        head: "head";
+        lips: "lips";
+    }>>;
+}, z.core.$strict>;
+/**
+ * The API takes speaker detection as an object; agents may send a boolean. Agents also
+ * turn on reasoning for models without it, and speaker detection for a still image, and
+ * the API rejects both, so drop them rather than fail the whole request.
+ */
+export declare function parseModelOptions(value: unknown, request: {
+    model: string;
+    image?: boolean;
+}): z.infer<typeof modelOptionsSchema> | undefined;
+//# sourceMappingURL=model-options.d.ts.map

package/dist/tools/model-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-options.d.ts","sourceRoot":"","sources":["../../src/tools/model-options.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;kBA0BpB,CAAC;AAIZ;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,OAAO,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC1C,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,GAAG,SAAS,CAShD"}

package/dist/tools/model-options.js

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+// Public model controls accepted by the generation API. Do not expose service-only options.
+export const modelOptionsSchema = z
+    .object({
+    sync_mode: z.enum(['bounce', 'loop', 'cut_off', 'silence', 'remap']).optional(),
+    temperature: z.number().min(0).max(1).nullable().optional(),
+    active_speaker_detection: z
+        .union([
+        z.boolean(),
+        z
+            .object({
+            auto_detect: z.boolean().optional(),
+            use_v2: z.boolean().optional(),
+            v3: z.boolean().optional(),
+            face_image: z.string().optional(),
+            frame_number: z.number().int().nonnegative().optional(),
+            coordinates: z.tuple([z.number(), z.number()]).optional(),
+        })
+            .strict(),
+    ])
+        .optional(),
+    occlusion_detection_enabled: z.boolean().optional(),
+    reasoning_enabled: z
+        .boolean()
+        .optional()
+        .describe('Only lipsync-2-pro supports reasoning; it is ignored for other models.'),
+    model_mode: z.enum(['lips', 'face', 'head']).optional(),
+})
+    .strict();
+const REASONING_MODELS = new Set(['lipsync-2-pro', 'sync-2-pro']);
+/**
+ * The API takes speaker detection as an object; agents may send a boolean. Agents also
+ * turn on reasoning for models without it, and speaker detection for a still image, and
+ * the API rejects both, so drop them rather than fail the whole request.
+ */
+export function parseModelOptions(value, request) {
+    const options = modelOptionsSchema.optional().parse(value);
+    if (!options)
+        return options;
+    if (typeof options.active_speaker_detection === 'boolean') {
+        options.active_speaker_detection = { auto_detect: options.active_speaker_detection };
+    }
+    if (!REASONING_MODELS.has(request.model))
+        delete options.reasoning_enabled;
+    if (request.image)
+        delete options.active_speaker_detection;
+    return options;
+}

package/dist/tools/organization-choice.d.ts

@@ -0,0 +1,9 @@
+import { type HttpClient } from '../http-client.js';
+import type { McpToolDefinition } from './generator.js';
+import { type CredentialKind } from './organizations.js';
+/**
+ * Adds an optional organizationId that runs one paid create in another organization,
+ * and reports the organization each call ran in.
+ */
+export declare function withOrganizationChoice(tool: McpToolDefinition, http: HttpClient, credential: CredentialKind): McpToolDefinition;
+//# sourceMappingURL=organization-choice.d.ts.map

package/dist/tools/organization-choice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"organization-choice.d.ts","sourceRoot":"","sources":["../../src/tools/organization-choice.ts"],"names":[],"mappings":"AAEA,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAQrE,OAAO,KAAK,EAAE,iBAAiB,EAAsB,MAAM,gBAAgB,CAAC;AAC5E,OAAO,EACL,KAAK,cAAc,EAOpB,MAAM,oBAAoB,CAAC;AAuE5B;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,iBAAiB,EACvB,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,cAAc,GACzB,iBAAiB,CA6FnB"}

package/dist/tools/organization-choice.js

@@ -0,0 +1,136 @@
+import { z } from 'zod';
+import { ApiRequestError } from '../http-client.js';
+import { chosenOrganization, runInOrganization, } from '../organization-selection.js';
+import { sessionOf, summary, defaultOrganization, apiKeyBound, readAccountAs, organizationSummarySchema, } from './organizations.js';
+// Longest a result waits to name its default organization; past it, `organization` is omitted.
+const ORGANIZATION_LOOKUP_MS = 2_000;
+/** Paid creates, and the estimates that quote them, that take a one-call organizationId. */
+const PER_CALL_ORGANIZATION_TOOLS = new Set([
+    'lipsync_create',
+    'lipsync_create-from-assets',
+    'lipsync_create-timeline',
+    'dubbing_create',
+    'translation-previews_create',
+    'translation-previews_estimate',
+    'dialogue-previews_create',
+    'dialogue-videos_create',
+    'dialogue-videos_estimate',
+    'generations_create',
+    'generations_estimate-cost',
+    // From the batch tools (CRAFT-7781); applies once they are registered.
+    'batches_create',
+]);
+const organizationOutput = organizationSummarySchema
+    .optional()
+    .describe('The Sync organization this call ran in.');
+const organizationIdInput = z
+    .uuid()
+    .optional()
+    .describe('Run only this call in another of the user’s Sync organizations, by id from organizations_list, when the user asks for it (for example “generate this in the Acme org”). The session keeps its organization; reads of the ids this call returns stay in this organization. Omit to use the session’s organization.');
+// Ids a create returns: its job, generation, project or output asset.
+function returnedIds(result) {
+    if (!result || typeof result !== 'object' || Array.isArray(result))
+        return [];
+    return Object.entries(result).flatMap(([key, value]) => (key === 'id' || key.endsWith('Id')) && z.uuid().safeParse(value).success
+        ? [value]
+        : []);
+}
+async function organizationForCall(http, credential, session, organizationId, signal) {
+    const active = chosenOrganization();
+    if (active?.id === organizationId)
+        return { organization: active, scoped: true };
+    // Running in the credential's own organization needs no header.
+    if (credential === 'api_key' || !active) {
+        const own = credential === 'api_key'
+            ? await defaultOrganization(http, session, signal)
+            : await defaultOrganization(http, session, signal).catch(() => undefined);
+        if (own?.id === organizationId)
+            return { organization: own, scoped: false };
+        if (credential === 'api_key')
+            throw apiKeyBound(own);
+    }
+    const account = await readAccountAs(http, organizationId, signal);
+    return { organization: summary(account.organization), scoped: true };
+}
+function withOrganization(result, organization) {
+    if (!organization || !result || typeof result !== 'object' || Array.isArray(result))
+        return result;
+    return { ...result, organization };
+}
+/**
+ * Adds an optional organizationId that runs one paid create in another organization,
+ * and reports the organization each call ran in.
+ */
+export function withOrganizationChoice(tool, http, credential) {
+    if (!PER_CALL_ORGANIZATION_TOOLS.has(tool.name))
+        return tool;
+    const run = async (args, context, handler) => {
+        const { organizationId, ...fields } = args;
+        const session = sessionOf();
+        // Ids a create returns are read in the organization it ran in, even after a switch.
+        // API keys have one organization and never send the header, so they remember nothing.
+        // `ranIn` is fixed before the call starts, so it never depends on naming the organization.
+        const remember = (ids, ranIn) => {
+            if (credential === 'user')
+                session.rememberIds(ids, ranIn);
+        };
+        const execute = async (ranIn) => {
+            try {
+                return await handler(fields);
+            }
+            catch (error) {
+                // An uncertain admission names its generation; recovery must read the same organization.
+                if (error instanceof ApiRequestError && error.generationId)
+                    remember([error.generationId], ranIn);
+                throw error;
+            }
+        };
+        const finish = (result, ranIn, organization) => {
+            remember(returnedIds(tool.resultFormat === 'mcp' ? result.structuredContent : result), ranIn);
+            return { result, organization };
+        };
+        if (typeof organizationId !== 'string') {
+            const active = chosenOrganization();
+            // Read alongside the call, bounded, so naming the organization never delays a result.
+            const deadline = AbortSignal.timeout(ORGANIZATION_LOOKUP_MS);
+            const lookup = active
+                ? Promise.resolve(active)
+                : defaultOrganization(http, session, context?.signal ? AbortSignal.any([context.signal, deadline]) : deadline).catch(() => undefined);
+            const result = await execute(active ?? null);
+            return finish(result, active ?? null, await lookup);
+        }
+        const { organization, scoped } = await organizationForCall(http, credential, session, organizationId, context?.signal);
+        const ranIn = scoped ? organization : null;
+        const result = await runInOrganization(ranIn ?? undefined, () => execute(ranIn));
+        return finish(result, ranIn, organization);
+    };
+    const definition = {
+        ...tool,
+        inputSchema: { ...tool.inputSchema, organizationId: organizationIdInput },
+        ...(tool.outputSchema
+            ? { outputSchema: { ...tool.outputSchema, organization: organizationOutput } }
+            : {}),
+    };
+    if (tool.resultFormat === 'mcp')
+        return {
+            ...definition,
+            resultFormat: 'mcp',
+            handler: async (args, context) => {
+                const { result, organization } = await run(args, context, (fields) => tool.handler(fields, context));
+                if (result.isError || !organization)
+                    return result;
+                return {
+                    ...result,
+                    structuredContent: withOrganization(result.structuredContent, organization),
+                };
+            },
+        };
+    return {
+        ...definition,
+        resultFormat: 'json',
+        handler: async (args, context) => {
+            const { result, organization } = await run(args, context, (fields) => tool.handler(fields, context));
+            return withOrganization(result, organization);
+        },
+    };
+}

package/dist/tools/organizations.d.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+import { ApiRequestError, type HttpClient } from '../http-client.js';
+import { OrganizationSession, type OrganizationSummary } from '../organization-selection.js';
+import type { McpToolDefinition } from './generator.js';
+/** GET route listing the caller's organizations (sync-api-v2, CRAFT-7789). */
+export declare const ORGANIZATIONS_PATH = "/v2/account/organizations";
+/** API keys act for one organization; OAuth and device-auth sessions can choose per request. */
+export type CredentialKind = 'api_key' | 'user';
+/**
+ * Next step for a refused organization: the API's own suggestion (for a connection without
+ * a grant, reconnecting and ticking that organization), then what not to do.
+ */
+export declare function organizationNextStep(error: ApiRequestError): string | undefined;
+export declare function switchHint(credential: CredentialKind): string;
+declare const planSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strip>;
+declare const generationLimitsSchema: z.ZodObject<{
+    concurrency: z.ZodNumber;
+    maxOutputDurationSeconds: z.ZodNumber;
+}, z.core.$strip>;
+declare const accountOrganizationSchema: z.ZodObject<{
+    id: z.ZodUUID;
+    name: z.ZodNullable<z.ZodString>;
+    role: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const featuresSchema: z.ZodArray<z.ZodString>;
+export type AccountOverview = {
+    organization?: z.infer<typeof accountOrganizationSchema>;
+    credentialType?: string;
+    plan?: z.infer<typeof planSchema>;
+    limits?: z.infer<typeof generationLimitsSchema>;
+    features?: string[];
+};
+/** GET /v2/account, read field by field so one unexpected field never hides the rest. */
+export declare function parseAccountOverview(value: unknown): AccountOverview;
+export declare function sessionOf(): OrganizationSession;
+export declare function summary(organization: {
+    id: string;
+    name: string | null;
+}): OrganizationSummary;
+/** The credential's own organization, read once a minute at most. */
+export declare function defaultOrganization(http: HttpClient, session: OrganizationSession, signal: AbortSignal | undefined): Promise<OrganizationSummary>;
+export declare function apiKeyBound(organization: OrganizationSummary | undefined): Error;
+/** Reads the account as `organizationId`; refuses unless the API answered for that organization. */
+export declare function readAccountAs(http: HttpClient, organizationId: string, signal: AbortSignal | undefined): Promise<AccountOverview & {
+    organization: z.infer<typeof accountOrganizationSchema>;
+}>;
+export declare const organizationSummarySchema: z.ZodObject<{
+    id: z.ZodUUID;
+    name: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export declare function createOrganizationTools(http: HttpClient, credential: CredentialKind): McpToolDefinition[];
+export {};
+//# sourceMappingURL=organizations.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"organizations.d.ts","sourceRoot":"","sources":["../../src/tools/organizations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,EAGL,mBAAmB,EACnB,KAAK,mBAAmB,EACzB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,8BAA8B,CAAC;AAE9D,gGAAgG;AAChG,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,MAAM,CAAC;AAqBhD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS,CAO/E;AAED,wBAAgB,UAAU,CAAC,UAAU,EAAE,cAAc,GAAG,MAAM,CAE7D;AAED,QAAA,MAAM,UAAU;;;iBAAiD,CAAC;AAClE,QAAA,MAAM,sBAAsB;;;iBAG1B,CAAC;AACH,QAAA,MAAM,yBAAyB;;;;iBAI7B,CAAC;AAEH,eAAO,MAAM,cAAc,yBAIxB,CAAC;AAEJ,MAAM,MAAM,eAAe,GAAG;IAC5B,YAAY,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;IACzD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,IAAI,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;IAClC,MAAM,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;IAChD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB,CAAC;AAQF,yFAAyF;AACzF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAapE;AAeD,wBAAgB,SAAS,IAAI,mBAAmB,CAE/C;AAED,wBAAgB,OAAO,CAAC,YAAY,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,mBAAmB,CAE9F;AAOD,qEAAqE;AACrE,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,mBAAmB,EAC5B,MAAM,EAAE,WAAW,GAAG,SAAS,GAC9B,OAAO,CAAC,mBAAmB,CAAC,CAQ9B;AAED,wBAAgB,WAAW,CAAC,YAAY,EAAE,mBAAmB,GAAG,SAAS,GAAG,KAAK,CAIhF;AAED,oGAAoG;AACpG,wBAAsB,aAAa,CACjC,IAAI,EAAE,UAAU,EAChB,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,WAAW,GAAG,SAAS,GAC9B,OAAO,CAAC,eAAe,GAAG;IAAE,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAA;CAAE,CAAC,CAcxF;AAaD,eAAO,MAAM,yBAAyB;;;iBAA0D,CAAC;AAsEjG,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,cAAc,GACzB,iBAAiB,EAAE,CAkErB"}