docs-combiner 0.4.0 → 1.0.0

package/dist/agentApi/agentControlClaim.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldClaimAgentControl = shouldClaimAgentControl;
+const AGENT_CONTROL_CLAIMING_METHODS = new Set([
+    'setupCampaignWorkspace',
+    'createCampaignGroup',
+    'createWorkspaceFolder',
+    'startGeneration',
+    'patchSessionInfo',
+    'fillGeoBlock',
+    'setCreativeSelections',
+    'setApproachMatrix',
+    'patchGenerated',
+    'loadContent',
+    'uploadImages',
+    'checkImages',
+    'regeneratePair',
+    'regenerateImages',
+]);
+function shouldClaimAgentControl(method, options) {
+    if ((options === null || options === void 0 ? void 0 : options.claimAgentControl) === false)
+        return false;
+    if ((options === null || options === void 0 ? void 0 : options.claimAgentControl) === true)
+        return true;
+    return AGENT_CONTROL_CLAIMING_METHODS.has(method);
+}

package/dist/agentApi/approachMatrixView.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildApproachMatrixView = buildApproachMatrixView;
+const promptOverrides_1 = require("../promptOverrides");
+function buildApproachMatrixView(enabled, rows) {
+    const textIndices = (0, promptOverrides_1.textApproachIndicesFromMatrix)(rows);
+    return {
+        ok: true,
+        enabled,
+        rows,
+        derived: {
+            selectedTextApproachIndices: textIndices,
+            selectedTextApproachNumbers: textIndices.map(index => index + 1),
+            imageApproachCounts: (0, promptOverrides_1.imageApproachCountsFromMatrix)(rows),
+        },
+        format: 'Array<[imageApproachNumber, textApproachNumbers[]]>',
+        example: [[4, [3, 8, 10, 1]], [6, [3, 2, 4]]],
+    };
+}

package/dist/agentApi/capabilitiesMeta.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAgentCapabilitiesMeta = buildAgentCapabilitiesMeta;
+const catalogUrlPresets_1 = require("./catalogUrlPresets");
+function buildAgentCapabilitiesMeta() {
+    return {
+        actions: {
+            listSessions: true,
+            createSession: true,
+            readDriveCatalog: true,
+            setupCampaignWorkspace: true,
+            readSession: true,
+            patchSession: true,
+            readValidation: true,
+            readGenerated: true,
+            patchGenerated: true,
+            readLogs: true,
+            readJobStatus: true,
+            readApproachMatrix: true,
+            setApproachMatrix: true,
+            loadContent: true,
+            uploadImages: true,
+            checkImages: true,
+            regeneratePair: true,
+            regenerateImages: true,
+            setAgentControlMode: true,
+            readAgentControlStatus: true,
+            startGeneration: true,
+            exportCatalog: true,
+            createCampaignGroup: true,
+            createWorkspaceFolder: true,
+        },
+        fields: {
+            sessionPatch: [
+                'drive.groupName',
+                'drive.workspaceFolderId',
+                'drive.workspaceName',
+                'drive.offer',
+                'generation.product',
+                'generation.additionalInfo',
+                'generation.firstGeo',
+                'generation.firstPriceWithCurrency',
+                'generation.firstLink',
+                'generation.geoBlock',
+                'catalogUrlSettings',
+                'creativeSelections',
+                'creativeSelections.matrix',
+                'promptSettings.approachMatrix',
+            ],
+            setupCampaign: ['groupName', 'workspaceFolderId', 'workspaceName', 'offer', 'generation', 'creativeSelections', 'catalogUrlSettings'],
+            driveCatalog: ['offers', 'campaignGroups', 'workspaces', 'campaignsCsv'],
+            createCampaignGroup: ['name'],
+            createWorkspaceFolder: ['groupName', 'name', 'select'],
+            catalogUrlSettings: {
+                includeTextApproach: 'boolean',
+                includeCreoApproach: 'boolean',
+                includeImageAspect: 'boolean',
+                textApproachParam: 'string (default sub19)',
+                creoApproachParam: 'string (default sub20)',
+                imageAspectParam: 'string (default sub18)',
+                extraMacrosPreset: '"redtrack" | "keitaro"',
+                extraMacros: 'string — custom tail; overrides extraMacrosPreset if both sent',
+                presets: catalogUrlPresets_1.CATALOG_LINK_EXTRA_MACROS_PRESETS,
+            },
+            generation: ['content', 'images', 'catalog', 'all'],
+            generationAsync: 'POST .../generate with { "async": true } returns 202; poll GET .../jobs/{jobId}?wait=1',
+            sessionActions: ['load-content', 'upload-images', 'check-images', 'regenerate-pair', 'regenerate-images'],
+            generatedPatch: ['titles', 'texts', 'images'],
+            approachMatrix: {
+                read: 'getApproachMatrix()',
+                write: 'setApproachMatrix({ enabled: true, rows: [[4, [3, 8, 10, 1]], [6, [3, 2, 4]]] })',
+                viaCreativeSelections: 'setCreativeSelections({ matrix: { enabled: true, rows: [[4, [3, 8, 10, 1]]] } })',
+            },
+            escalation: 'On { ok: false } and validation.blocking — optional escalation block with userMessage for the human operator',
+        },
+        jobs: ['content', 'images', 'regenerateImages', 'replaceCatalog', 'loadContent', 'uploadImages', 'checkImages'],
+    };
+}

package/dist/agentApi/catalogUrlPresets.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CATALOG_LINK_EXTRA_MACROS_PRESETS = exports.DEFAULT_CATALOG_LINK_KEITARO_MACROS = exports.DEFAULT_CATALOG_LINK_EXTRA_MACROS = void 0;
+exports.resolveCatalogLinkExtraMacros = resolveCatalogLinkExtraMacros;
+exports.DEFAULT_CATALOG_LINK_EXTRA_MACROS = 'sub1={{ad.id}}&sub2={{adset.id}}&sub3={{campaign.id}}&sub4={{ad.name}}&sub5={{adset.name}}&sub6={{campaign.name}}&sub7={{placement}}&sub8={{site_source_name}}&utm_source=facebook&utm_medium=paid';
+exports.DEFAULT_CATALOG_LINK_KEITARO_MACROS = 'utm_campaign={{campaign.name}}&utm_source={{site_source_name}}&utm_placement={{placement}}&campaign_id={{campaign.id}}&adset_id={{adset.id}}&ad_id={{ad.id}}&adset_name={{adset.name}}&ad_name={{ad.name}}';
+exports.CATALOG_LINK_EXTRA_MACROS_PRESETS = {
+    redtrack: exports.DEFAULT_CATALOG_LINK_EXTRA_MACROS,
+    keitaro: exports.DEFAULT_CATALOG_LINK_KEITARO_MACROS,
+};
+function resolveCatalogLinkExtraMacros(presetRaw, extraMacrosRaw, hasPreset, hasExtraMacros) {
+    if (hasExtraMacros) {
+        return { ok: true, value: String(extraMacrosRaw !== null && extraMacrosRaw !== void 0 ? extraMacrosRaw : '') };
+    }
+    if (hasPreset) {
+        const preset = String(presetRaw !== null && presetRaw !== void 0 ? presetRaw : '').trim().toLowerCase();
+        if (!(preset in exports.CATALOG_LINK_EXTRA_MACROS_PRESETS)) {
+            return {
+                ok: false,
+                error: `Unknown extraMacrosPreset: ${String(presetRaw)}. Use "redtrack" or "keitaro".`,
+            };
+        }
+        return { ok: true, value: exports.CATALOG_LINK_EXTRA_MACROS_PRESETS[preset] };
+    }
+    return { ok: true, value: '' };
+}

package/dist/agentApi/constants.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_AGENT_API_PORT = exports.DEFAULT_AGENT_API_HOST = void 0;
+exports.getDefaultAgentApiBaseUrl = getDefaultAgentApiBaseUrl;
+exports.DEFAULT_AGENT_API_HOST = '127.0.0.1';
+exports.DEFAULT_AGENT_API_PORT = 17321;
+function getDefaultAgentApiBaseUrl() {
+    const rawPort = Number(process.env.DOCS_COMBINER_AGENT_API_PORT);
+    const port = Number.isInteger(rawPort) && rawPort > 0 && rawPort <= 65535 ? rawPort : exports.DEFAULT_AGENT_API_PORT;
+    return `http://${exports.DEFAULT_AGENT_API_HOST}:${port}`;
+}

package/dist/agentApi/creativeSelections.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAgentCreativeSelections = buildAgentCreativeSelections;
+const promptOverrides_1 = require("../promptOverrides");
+function buildAgentCreativeSelections(textApproaches, imageCounts, matrixEnabled, matrix, maxPerApproach = promptOverrides_1.MAX_IMAGES_PER_CREO_APPROACH) {
+    const selectedImageApproachIndices = imageCounts
+        .map((count, index) => (count > 0 ? index : -1))
+        .filter(index => index >= 0);
+    return {
+        textApproaches: {
+            selectedIndices: textApproaches,
+            selectedNumbers: textApproaches.map(index => index + 1),
+        },
+        imageApproaches: {
+            counts: imageCounts,
+            selectedIndices: selectedImageApproachIndices,
+            selectedNumbers: selectedImageApproachIndices.map(index => index + 1),
+            maxPerApproach,
+        },
+        matrix: {
+            enabled: matrixEnabled,
+            rows: matrix,
+        },
+    };
+}

package/dist/agentApi/escalation.js

@@ -0,0 +1,221 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildEscalation = buildEscalation;
+exports.shouldAttachEscalation = shouldAttachEscalation;
+exports.buildValidationEscalation = buildValidationEscalation;
+exports.inferEscalationFromError = inferEscalationFromError;
+exports.enrichAgentFailure = enrichAgentFailure;
+function buildEscalation(input) {
+    return input;
+}
+function shouldAttachEscalation(error) {
+    const lower = error.toLowerCase();
+    if (!lower.trim())
+        return false;
+    if (lower.includes('already running'))
+        return false;
+    if (lower.includes('retry shortly'))
+        return false;
+    if (lower.includes('unknown target'))
+        return false;
+    if (lower.includes('unknown job id'))
+        return false;
+    return true;
+}
+function escalationFromCheckId(checkId) {
+    switch (checkId) {
+        case 'googleAuth':
+            return buildEscalation({
+                required: true,
+                kind: 'missing_credentials',
+                userMessage: 'Нужен вход в Google Drive в Комбайнере (Credentials → Login with Google). После входа повторите шаг агента.',
+                suggestedAction: 'open_credentials',
+            });
+        case 'openRouterKey':
+            return buildEscalation({
+                required: true,
+                kind: 'missing_credentials',
+                userMessage: 'В Комбайнере не указан API-ключ OpenRouter (Credentials). Добавьте ключ и повторите шаг агента.',
+                suggestedAction: 'open_credentials',
+            });
+        case 'driveFolder':
+            return buildEscalation({
+                required: true,
+                kind: 'needs_configuration',
+                userMessage: 'Не выбрана рабочая папка Google Drive. Выберите группу и папку в UI или вызовите setup-campaign через Agent API.',
+                suggestedAction: 'configure_session',
+            });
+        case 'product':
+            return buildEscalation({
+                required: true,
+                kind: 'needs_configuration',
+                userMessage: 'Не заполнено поле «Товар». Укажите product в setup-campaign / PATCH сессии или в UI, затем повторите генерацию.',
+                suggestedAction: 'configure_session',
+            });
+        case 'geoBlock':
+            return buildEscalation({
+                required: true,
+                kind: 'needs_configuration',
+                userMessage: 'Не заполнен блок гео (хотя бы одна строка). Передайте geo-block / generationMarkets или заполните в UI.',
+                suggestedAction: 'configure_session',
+            });
+        case 'creativeSelections':
+            return buildEscalation({
+                required: true,
+                kind: 'needs_configuration',
+                userMessage: 'Не выбраны креативные подходы (тексты и изображения). Настройте creative-selections / approach-matrix или UI.',
+                suggestedAction: 'configure_session',
+            });
+        case 'generatedPairsComplete':
+            return buildEscalation({
+                required: true,
+                kind: 'needs_manual_ui',
+                userMessage: 'Сгенерированные пары заголовок+текст неполные (например, есть текст без заголовка). В UI нажмите «Перегенерировать» у проблемной пары или заполните вручную, затем снова экспортируйте каталог. Агент: POST .../actions/regenerate-pair { "index": N }.',
+                suggestedAction: 'take_manual_control',
+            });
+        default:
+            return null;
+    }
+}
+function buildValidationEscalation(input) {
+    if (input.blocking.length > 0) {
+        const primary = escalationFromCheckId(input.blocking[0].id);
+        if (primary) {
+            if (input.blocking.length === 1)
+                return primary;
+            const summary = input.blocking.map(check => check.message).join('; ');
+            return buildEscalation(Object.assign(Object.assign({}, primary), { userMessage: `Перед генерацией исправьте в Комбайнере: ${summary}` }));
+        }
+        return buildEscalation({
+            required: true,
+            kind: 'needs_configuration',
+            userMessage: `Перед генерацией исправьте в Комбайнере: ${input.blocking.map(check => check.message).join('; ')}`,
+            suggestedAction: 'configure_session',
+        });
+    }
+    if (input.hints.length > 0) {
+        return buildEscalation({
+            required: false,
+            kind: 'needs_configuration',
+            userMessage: 'Оффер ещё не привязан в campaigns.csv. Привяжите оффер через setup-campaign или селектор в UI — иначе product/описание могут подтянуться неполностью.',
+            suggestedAction: 'configure_session',
+        });
+    }
+    return undefined;
+}
+function inferEscalationFromError(error) {
+    const text = String(error !== null && error !== void 0 ? error : '').trim();
+    if (!text || !shouldAttachEscalation(text))
+        return null;
+    const lower = text.toLowerCase();
+    if (lower.includes('openrouter api key')) {
+        return buildEscalation({
+            required: true,
+            kind: 'missing_credentials',
+            userMessage: 'В Комбайнере не указан API-ключ OpenRouter (Credentials). Добавьте ключ и повторите шаг агента.',
+            suggestedAction: 'open_credentials',
+        });
+    }
+    if (lower.includes('not logged in') ||
+        lower.includes('google drive auth') ||
+        lower.includes('google authentication') ||
+        lower.includes('valid token')) {
+        return buildEscalation({
+            required: true,
+            kind: 'missing_credentials',
+            userMessage: 'Нужен вход в Google Drive в Комбайнере (Credentials → Login with Google). После входа повторите шаг агента.',
+            suggestedAction: 'open_credentials',
+        });
+    }
+    if (lower.includes('campaigns root folder is not configured')) {
+        return buildEscalation({
+            required: true,
+            kind: 'needs_configuration',
+            userMessage: 'В Credentials не указана «Папка с кампаниями». Задайте её в UI (Credentials) или откройте сессию, где она уже настроена.',
+            suggestedAction: 'open_credentials',
+        });
+    }
+    if (lower.includes('working folder') || lower.includes('working drive folder')) {
+        return buildEscalation({
+            required: true,
+            kind: 'needs_configuration',
+            userMessage: 'Не выбрана рабочая папка Google Drive. Вызовите setup-campaign или выберите папку в UI.',
+            suggestedAction: 'configure_session',
+        });
+    }
+    if (lower.includes('product.png') || lower.includes('product image')) {
+        return buildEscalation({
+            required: true,
+            kind: 'needs_drive_file',
+            userMessage: 'В рабочей папке нет product.png/jpg/webp. Загрузите файл на Drive, привяжите оффер в campaigns.csv или выберите оффер в UI.',
+            suggestedAction: 'upload_drive_file',
+        });
+    }
+    if (lower.includes('agent handlers not ready') || lower.includes('agent api is not ready')) {
+        return buildEscalation({
+            required: true,
+            kind: 'session_not_ready',
+            userMessage: 'Сессия Комбайнера ещё загружается. Подождите несколько секунд и повторите запрос (GET /api/windows/{id}).',
+            suggestedAction: 'retry_later',
+        });
+    }
+    if (lower.includes('no session with agent api ready')) {
+        return buildEscalation({
+            required: true,
+            kind: 'session_not_ready',
+            userMessage: 'Нет готовой сессии Комбайнера с Agent API. Откройте окно приложения или POST /api/windows и дождитесь ready.',
+            suggestedAction: 'retry_later',
+        });
+    }
+    if (lower.includes('несколько изображений') ||
+        lower.includes('multiple images') ||
+        lower.includes('exactly one')) {
+        return buildEscalation({
+            required: true,
+            kind: 'needs_drive_file',
+            userMessage: 'В папке оффера на Drive должно быть ровно одно изображение продукта (любое имя файла). Удалите лишние картинки или объедините в один файл.',
+            suggestedAction: 'upload_drive_file',
+        });
+    }
+    if (lower.includes('incomplete_generated_pairs') ||
+        lower.includes('catalog export blocked')) {
+        return buildEscalation({
+            required: true,
+            kind: 'needs_manual_ui',
+            userMessage: 'Каталог не собран: одна или несколько пар «заголовок + текст» неполные. Перегенерируйте проблемные пары в UI или через POST .../actions/regenerate-pair, затем повторите catalog.',
+            suggestedAction: 'take_manual_control',
+        });
+    }
+    if (lower.includes('product is required') ||
+        lower.includes('at least one geo') ||
+        lower.includes('text creative approaches') ||
+        lower.includes('image creative approach') ||
+        lower.includes('link is required') ||
+        lower.includes('invalid link url') ||
+        lower.includes('groupname is required') ||
+        lower.includes('provide workspacefolderid') ||
+        lower.includes('select at least one geo')) {
+        return buildEscalation({
+            required: true,
+            kind: 'needs_configuration',
+            userMessage: `Агенту не хватает данных сессии: ${text}. Заполните поля через setup-campaign / PATCH / geo-block или в UI.`,
+            suggestedAction: 'configure_session',
+        });
+    }
+    return buildEscalation({
+        required: true,
+        kind: 'needs_configuration',
+        userMessage: `Агент не смог продолжить: ${text}. Проверьте сессию в UI или передайте оператору для эскалации в Комбайнер.`,
+        suggestedAction: 'configure_session',
+    });
+}
+function enrichAgentFailure(body) {
+    var _a, _b;
+    if (body.ok !== false)
+        return body;
+    if (body.escalation && typeof body.escalation === 'object')
+        return body;
+    const error = String((_b = (_a = body.error) !== null && _a !== void 0 ? _a : body.message) !== null && _b !== void 0 ? _b : '');
+    const escalation = inferEscalationFromError(error);
+    return escalation ? Object.assign(Object.assign({}, body), { escalation }) : body;
+}

package/dist/agentApi/generatedPairsGuard.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findIncompleteGeneratedPairs = findIncompleteGeneratedPairs;
+exports.shouldBlockCatalogForGeneratedPairs = shouldBlockCatalogForGeneratedPairs;
+exports.formatIncompletePairsUserAlert = formatIncompletePairsUserAlert;
+exports.buildCatalogBlockedByIncompletePairsFailure = buildCatalogBlockedByIncompletePairsFailure;
+exports.buildIncompletePairsValidationMessage = buildIncompletePairsValidationMessage;
+function findIncompleteGeneratedPairs(titles, texts) {
+    var _a, _b, _c, _d;
+    const len = Math.max(titles.length, texts.length);
+    if (len === 0)
+        return [];
+    const incomplete = [];
+    for (let pairIndex = 0; pairIndex < len; pairIndex++) {
+        const titleData = titles[pairIndex];
+        const textData = texts[pairIndex];
+        const generating = Boolean((titleData === null || titleData === void 0 ? void 0 : titleData.generating) || (textData === null || textData === void 0 ? void 0 : textData.generating));
+        const title = String((_a = titleData === null || titleData === void 0 ? void 0 : titleData.title) !== null && _a !== void 0 ? _a : '').trim();
+        const text = String((_b = textData === null || textData === void 0 ? void 0 : textData.text) !== null && _b !== void 0 ? _b : '').trim();
+        const missingTitle = generating || !title || Boolean(titleData === null || titleData === void 0 ? void 0 : titleData.failed);
+        const missingText = generating || !text || Boolean(textData === null || textData === void 0 ? void 0 : textData.failed);
+        if (missingTitle || missingText) {
+            incomplete.push({
+                index: (_d = (_c = titleData === null || titleData === void 0 ? void 0 : titleData.index) !== null && _c !== void 0 ? _c : textData === null || textData === void 0 ? void 0 : textData.index) !== null && _d !== void 0 ? _d : pairIndex + 1,
+                pairIndex,
+                geo: (titleData === null || titleData === void 0 ? void 0 : titleData.geo) || (textData === null || textData === void 0 ? void 0 : textData.geo),
+                missingTitle,
+                missingText,
+                generating,
+                titleError: titleData === null || titleData === void 0 ? void 0 : titleData.errorMessage,
+                textError: textData === null || textData === void 0 ? void 0 : textData.errorMessage,
+            });
+        }
+    }
+    return incomplete;
+}
+function shouldBlockCatalogForGeneratedPairs(input) {
+    const hasGeneratedStructure = input.titles.length > 0 || input.texts.length > 0;
+    if (!hasGeneratedStructure) {
+        return { block: false, incomplete: [] };
+    }
+    const incomplete = findIncompleteGeneratedPairs(input.titles, input.texts);
+    return { block: incomplete.length > 0, incomplete };
+}
+function describeIncompletePair(pair) {
+    const geoSuffix = pair.geo ? ` (${pair.geo})` : '';
+    if (pair.generating) {
+        return `пара ${pair.index}${geoSuffix} — генерация ещё идёт`;
+    }
+    if (pair.missingTitle && pair.missingText) {
+        return `пара ${pair.index}${geoSuffix} — заголовок и текст не получены`;
+    }
+    if (pair.missingTitle) {
+        return `пара ${pair.index}${geoSuffix} — заголовок не получен`;
+    }
+    return `пара ${pair.index}${geoSuffix} — текст не получен`;
+}
+function formatIncompletePairsUserAlert(pairs) {
+    const details = pairs.map(describeIncompletePair).join('; ');
+    return `Нельзя собрать каталог: ${details}. Перегенерируйте проблемные пары (кнопка «Перегенерировать») или заполните поля вручную.`;
+}
+function buildCatalogBlockedByIncompletePairsFailure(pairs) {
+    const summary = pairs
+        .map(pair => {
+        const geoSuffix = pair.geo ? ` geo=${pair.geo}` : '';
+        if (pair.generating)
+            return `pair ${pair.index}${geoSuffix}: generation in progress`;
+        if (pair.missingTitle && pair.missingText)
+            return `pair ${pair.index}${geoSuffix}: title and text missing`;
+        if (pair.missingTitle)
+            return `pair ${pair.index}${geoSuffix}: title missing`;
+        return `pair ${pair.index}${geoSuffix}: text missing`;
+    })
+        .join('; ');
+    return {
+        ok: false,
+        error: `Catalog export blocked: incomplete generated pairs — ${summary}. Regenerate each pair via POST .../actions/regenerate-pair with { "index": N } (1-based pair number), or PATCH .../generated.`,
+        code: 'incomplete_generated_pairs',
+        incompletePairs: pairs,
+        action: 'regeneratePair',
+    };
+}
+function buildIncompletePairsValidationMessage(pairs) {
+    return pairs.map(describeIncompletePair).join('; ');
+}

package/dist/agentApi/httpHelpers.js

@@ -0,0 +1,77 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sendAgentJsonFailure = sendAgentJsonFailure;
+exports.sendAgentActionResponse = sendAgentActionResponse;
+exports.waitForAgentJobStatus = waitForAgentJobStatus;
+const escalation_1 = require("./escalation");
+const jobStatus_1 = require("./jobStatus");
+function sendAgentJsonFailure(res, status, body) {
+    res.status(status).json((0, escalation_1.enrichAgentFailure)(body));
+}
+function sendAgentActionResponse(res, response) {
+    var _a, _b;
+    if (!response.ok) {
+        sendAgentJsonFailure(res, response.status, { ok: false, error: response.error });
+        return;
+    }
+    if (((_a = response.result) === null || _a === void 0 ? void 0 : _a.ok) === false) {
+        sendAgentJsonFailure(res, 400, response.result);
+        return;
+    }
+    if (((_b = response.result) === null || _b === void 0 ? void 0 : _b.async) === true) {
+        res.status(202).json(response.result);
+        return;
+    }
+    res.json(response.result);
+}
+function waitForAgentJobStatus(callAgentRendererApi, sessionId, jobId, timeoutMs) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        const startedAt = Date.now();
+        let lastStatus = 'idle';
+        let initialRunId = null;
+        let sawRunning = false;
+        while (Date.now() - startedAt < timeoutMs) {
+            const response = yield callAgentRendererApi(sessionId, 'getJobStatus', { jobId });
+            if (!response.ok)
+                return response;
+            const job = (_a = response.result) === null || _a === void 0 ? void 0 : _a.job;
+            const status = String((_b = job === null || job === void 0 ? void 0 : job.status) !== null && _b !== void 0 ? _b : 'idle');
+            const runId = typeof (job === null || job === void 0 ? void 0 : job.runId) === 'number' ? job.runId : undefined;
+            if (initialRunId === null && typeof runId === 'number') {
+                initialRunId = runId;
+            }
+            lastStatus = status;
+            if (status === 'running') {
+                sawRunning = true;
+            }
+            if ((0, jobStatus_1.isTerminalAgentJobWait)({
+                jobId,
+                status,
+                runId,
+                initialRunId,
+                sawRunning,
+            })) {
+                return response;
+            }
+            yield new Promise(resolve => setTimeout(resolve, 500));
+        }
+        return {
+            ok: true,
+            result: {
+                ok: true,
+                job: { id: jobId, status: lastStatus, timedOut: true },
+                timedOut: true,
+            },
+        };
+    });
+}

package/dist/agentApi/imagesReadiness.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildImageBlockingFailureMessage = buildImageBlockingFailureMessage;
+exports.isImageSlotFailedWithoutUpload = isImageSlotFailedWithoutUpload;
+exports.isImageBlockingFailure = isImageBlockingFailure;
+exports.buildImagesReadiness = buildImagesReadiness;
+const regenerateImages_1 = require("./regenerateImages");
+function buildImageBlockingFailureMessage(img) {
+    var _a, _b, _c, _d, _e;
+    if ((0, regenerateImages_1.isImageSlotCheckTransportFailure)(img)) {
+        const detail = ((_a = img.errorMessage) === null || _a === void 0 ? void 0 : _a.trim()) || ((_b = img.checkResult) === null || _b === void 0 ? void 0 : _b.trim());
+        return detail
+            ? `Validator transport error (recheck, do not rebuild): ${detail}`
+            : 'Validator transport error (recheck, do not rebuild)';
+    }
+    if ((_c = img.errorMessage) === null || _c === void 0 ? void 0 : _c.trim())
+        return img.errorMessage.trim();
+    if (img.checkStatus === 'needs_rebuild' && ((_d = img.checkResult) === null || _d === void 0 ? void 0 : _d.trim()))
+        return img.checkResult.trim();
+    if (img.checkStatus === 'needs_rebuild')
+        return 'Validator: needs_rebuild';
+    if (!((_e = img.imageUrl) === null || _e === void 0 ? void 0 : _e.trim()))
+        return 'No image generated';
+    return 'Image slot incomplete';
+}
+/** Terminal problem slot that is not uploaded to Drive yet. */
+function isImageSlotFailedWithoutUpload(img) {
+    if (img.uploaded)
+        return false;
+    if ((0, regenerateImages_1.isImageSlotBusy)(img))
+        return false;
+    return (0, regenerateImages_1.isImageSlotFailed)(img) || img.checkStatus === 'needs_rebuild';
+}
+function isImageBlockingFailure(img) {
+    if ((0, regenerateImages_1.isImageSlotBusy)(img))
+        return false;
+    if ((0, regenerateImages_1.isImageSlotUploadedOk)(img))
+        return false;
+    if (isImageSlotFailedWithoutUpload(img))
+        return true;
+    if ((0, regenerateImages_1.isImageSlotPendingUpload)(img))
+        return false;
+    return (0, regenerateImages_1.isImageSlotFailed)(img);
+}
+function buildImagesReadiness(images, options) {
+    const total = images.length;
+    const uploaded = images.filter(img => img.uploaded).length;
+    const failedWithoutUpload = images.filter(isImageSlotFailedWithoutUpload);
+    const blockingFailures = images.filter(isImageBlockingFailure).map(img => ({
+        index: img.index,
+        errorMessage: buildImageBlockingFailureMessage(img),
+        checkFailed: Boolean(img.checkFailed),
+        recommendedAction: (0, regenerateImages_1.resolveImageSlotFailureAction)(img),
+    }));
+    const imagesReady = total > 0 &&
+        !(options === null || options === void 0 ? void 0 : options.busy) &&
+        uploaded === total &&
+        failedWithoutUpload.length === 0;
+    return { imagesReady, blockingFailures, uploaded, total };
+}