@appaflytech/zeyrek-ai-mcp 0.0.36 → 0.0.40

package/dist/tools/bpmRuntime.js

@@ -0,0 +1,396 @@
+import { guid, projectParam, environmentParam, pagingParams, asUserIdParam, readOnly, writes, updates } from './common.js';
+import { PolicyBlockError } from '../knowledge/policy.js';
+import { PlatformApiError } from '../platform/errors.js';
+import { assertProcessNotProduction, bpmIdentityHeaders } from './bpm.js';
+import { handle } from '../platform/responses.js';
+import { z } from 'zod';
+const asUserParam = z.string().min(1).optional()
+    .describe("Uygulama kullanıcısının kimliği (ham JWT ya da access_session_create'in tokenRefs'teki tok_… referansı). İstek gateway'in Studio jetonu yerine bu kişi adına gider; süreç başlatan ve görev eylemini yapan bu kişi olur.");
+const asUserIdBpmParam = asUserIdParam
+    .describe("Parolasız kullanıcı gözü (users satır id'si): istek gateway kimliğiyle gider ve 'impersonated-user-id' başlığını taşır, platform özneyi o kullanıcı olarak kurar. /bpm/* uçları platform şemasıyla [Authorize] edildiği için UYGULAMA JETONU bu uçlarda 401 alır — parolasız yol budur. Yalnız development ya da dal; asUser ile birlikte verilemez.");
+const expectFailureParam = z.boolean().optional()
+    .describe('true: bu çağrıda hata BEKLENİYOR (kasıtlı negatif test: bayat version 409, yetkisiz kişi 403). Ölçüm plansız hata saymaz.');
+const taskActions = ['claim', 'unclaim', 'complete', 'approve', 'reject', 'request-info', 'provide-info', 'reassign', 'undo', 'sign', 'start-assessment', 'submit-assessment'];
+const documentOperations = ['generate', 'stamp', 'print'];
+const instanceOperations = ['cancel', 'suspend', 'resume', 'withdraw', 'reopen', 'retry', 'skip', 'jump', 'watch', 'unwatch'];
+const maxInlineLedgerBytes = 256 * 1024;
+export function registerBpmRuntimeTools(server, platform) {
+    const config = platform.config;
+    server.registerTool('process_execute', {
+        title: 'Süreci başlat',
+        description: "Aktif sürümden süreç örneği başlatır (POST bpm/processes/{slug}/start). asUser verilirse başlatan o uygulama kullanıcısıdır; yetki process.start. Tanımda singleton: per-subject varsa aynı satırda açık örnek dönerse YENİ örnek açılmaz, mevcut örnek döner. importAt verilirse örnek başlangıçtan değil o düğümden açılır (POST bpm/instances/import — kâğıttan ya da eski sistemden yarı yolda geçiş): defterin ilk satırı instance-imported, startedAt tarihsel başlangıçtır (gelecek olamaz), düğüm tek görev açarsa assigneeUserId'ye atanır; düğüm başlangıç/bitiş ya da bölge içi olamaz; yetki process.manage. production hedefi istek gitmeden durur (BPM-001). Ayrıntı: platform_guide('bpm') §Yürütme ve kutu, §Operasyon.",
+        inputSchema: {
+            project: projectParam,
+            environment: environmentParam,
+            slug: z.string().min(1).max(100),
+            applicationId: guid.optional(),
+            subjectRowId: z.string().max(64).optional(),
+            vars: z.record(z.unknown()).optional(),
+            importAt: z.object({
+                nodeId: z.string().min(1).max(100),
+                assigneeUserId: z.string().max(64).optional(),
+                startedAt: z.string().min(10).max(40).describe('ISO 8601 tarihsel başlangıç')
+            }).optional().describe('yarı yolda örnek: başlangıç yerine bu düğümden açılır'),
+            asUser: asUserParam,
+            asUserId: asUserIdBpmParam,
+            expectFailure: expectFailureParam
+        },
+        annotations: writes
+    }, handle(config, async ({ project, environment, slug, applicationId, subjectRowId, vars, importAt, asUser, asUserId }) => {
+        assertProcessNotProduction('process_execute', environment, config);
+        if (importAt) {
+            if (Number.isNaN(Date.parse(importAt.startedAt)))
+                throw new PlatformApiError('process_execute: importAt.startedAt ISO 8601 tarih olmalı (istek gönderilmedi).', 400);
+            return platform.tenant('POST', project, '/bpm/instances/import', {
+                environment,
+                body: { slug, applicationId, nodeId: importAt.nodeId, assigneeUserId: importAt.assigneeUserId, subjectRowId, vars, startedAt: importAt.startedAt },
+                headers: await bpmIdentityHeaders(platform, 'process_execute', project, environment, { asUser, asUserId })
+            });
+        }
+        return platform.tenant('POST', project, `/bpm/processes/${encodeURIComponent(slug)}/start`, {
+            environment,
+            body: { applicationId, subjectRowId, vars },
+            headers: await bpmIdentityHeaders(platform, 'process_execute', project, environment, { asUser, asUserId })
+        });
+    }));
+    server.registerTool('process_trigger', {
+        title: 'Sürece olay gönder',
+        description: "kind signal: açık örneğe sinyal (POST bpm/signals) — bölge olay işleyicisi (region.on[]), completeOn bekleyen görev ya da 'membership-added'; 'withdraw' ve 'reopen' adları yerleşiktir, instanceId zorunlu. kind message: mesaj korelasyonu (POST bpm/messages) — wait düğümünde name + correlationKey ile bekleyen örnekleri ilerletir, eşleşen yoksa message start'lı tanımı başlatır; instanceId verilmez. correlationKey'siz mesaj o adı anahtarsız bekleyen BÜTÜN örnekleri ilerletir (bekleyen yoksa message start'lı BÜTÜN tanımları başlatır) — bu yüzden anahtarsız gönderim broadcast:true ister. Mesaj eventId en çok 150 karakter. eventId verirseniz aynı olay ikinci kez işlenmez. bufferSeconds (en çok 86400): alıcı yoksa mesaj o süre tamponda bekler ve sonradan mesaj bekleyen wait düğümü açılınca hemen tüketilir — yanıt 202 ve buffered:true. kind event-source: name adlı olay kaynağına olay (POST bpm/event-sources/{name}/events; eventId zorunlu, en çok 120 karakter, payload kaynağın correlationKey ifadesiyle mesaja döner). kind mail-source: sourceId'li e-posta kaynağını şimdi yoklar (POST bpm/mail-sources/{id}/poll; yanıt readCount, sentCount, unmatchedCount, skippedCount). Kaynaklar connector modülünde (process_event_source_create, process_mail_source_create).",
+        inputSchema: {
+            project: projectParam,
+            environment: environmentParam,
+            kind: z.enum(['signal', 'message', 'event-source', 'mail-source']).optional().describe('varsayılan signal'),
+            sourceId: guid.optional().describe('kind mail-source için e-posta kaynağı id'),
+            instanceId: guid.optional().describe('kind signal için zorunlu'),
+            correlationKey: z.string().max(200).optional().describe('kind message için'),
+            name: z.string().min(1).max(100).optional().describe("signal, message ve event-source için zorunlu; mail-source almaz. ör. 'duzenleme-istegi', 'membership-added', 'row-event'"),
+            payload: z.record(z.unknown()).optional(),
+            eventId: z.string().max(200).optional(),
+            broadcast: z.boolean().optional().describe('kind message: correlationKey olmadan bütün bekleyenlere gönderimi onaylar'),
+            bufferSeconds: z.number().int().min(0).max(86400).optional().describe('kind message: alıcı yoksa tamponda bekleme süresi (sn)'),
+            asUser: asUserParam,
+            asUserId: asUserIdBpmParam,
+            expectFailure: expectFailureParam
+        },
+        annotations: writes
+    }, handle(config, async ({ project, environment, kind, sourceId, instanceId, correlationKey, name, payload, eventId, broadcast, bufferSeconds, asUser, asUserId }) => {
+        assertProcessNotProduction('process_trigger', environment, config);
+        if (kind === 'event-source') {
+            if (!eventId)
+                throw new PlatformApiError("process_trigger: kind 'event-source' eventId ister — aynı olayın ikinci kez işlenmemesi ona bağlı (istek gönderilmedi).", 400);
+            if (eventId.length > 120)
+                throw new PlatformApiError('process_trigger: olay kaynağı eventId en çok 120 karakter (istek gönderilmedi).', 400);
+            if (!name)
+                throw new PlatformApiError("process_trigger: kind 'event-source' name (olay kaynağı adı) ister (istek gönderilmedi).", 400);
+            return platform.tenant('POST', project, `/bpm/event-sources/${encodeURIComponent(name)}/events`, { environment, body: { eventId, payload } });
+        }
+        if (kind === 'mail-source') {
+            if (!sourceId)
+                throw new PlatformApiError("process_trigger: kind 'mail-source' sourceId ister (process_mail_source_list) (istek gönderilmedi).", 400);
+            return platform.tenant('POST', project, `/bpm/mail-sources/${sourceId}/poll`, { environment });
+        }
+        if (!name)
+            throw new PlatformApiError(`process_trigger: kind '${kind ?? 'signal'}' name ister (istek gönderilmedi).`, 400);
+        if (kind === 'message') {
+            if (!correlationKey && !broadcast)
+                throw new PlatformApiError("process_trigger: correlationKey'siz mesaj o adı anahtarsız bekleyen bütün örnekleri ilerletir; bilerek yapıyorsanız broadcast:true verin (istek gönderilmedi).", 400);
+            if (eventId && eventId.length > 150)
+                throw new PlatformApiError('process_trigger: mesaj eventId en çok 150 karakter (istek gönderilmedi).', 400);
+            return platform.tenant('POST', project, '/bpm/messages', {
+                environment,
+                body: { name, correlationKey, payload, eventId, bufferSeconds },
+                headers: await bpmIdentityHeaders(platform, 'process_trigger', project, environment, { asUser, asUserId })
+            });
+        }
+        if (!instanceId)
+            throw new PlatformApiError("process_trigger: kind 'signal' instanceId ister (istek gönderilmedi).", 400);
+        return platform.tenant('POST', project, '/bpm/signals', {
+            environment,
+            body: { instanceId, name, payload, eventId },
+            headers: await bpmIdentityHeaders(platform, 'process_trigger', project, environment, { asUser, asUserId })
+        });
+    }));
+    server.registerTool('process_instance_list', {
+        title: 'Süreç örneklerini listele',
+        description: 'Süreç örneklerini listeler; tanım, durum, iş satırı ve başlatan ile süzülür.',
+        inputSchema: {
+            project: projectParam,
+            environment: environmentParam,
+            definitionId: guid.optional(),
+            state: z.enum(['running', 'waiting-timer', 'suspended', 'faulted', 'completed', 'cancelled', 'withdrawn', 'expired']).optional(),
+            subjectRowId: z.string().max(64).optional(),
+            initiatorUserId: z.string().max(64).optional(),
+            asUser: asUserParam,
+            asUserId: asUserIdBpmParam,
+            ...pagingParams
+        },
+        annotations: readOnly
+    }, handle(config, async ({ project, environment, asUser, asUserId, ...query }) => platform.tenant('GET', project, '/bpm/instances', {
+        environment,
+        query,
+        headers: await bpmIdentityHeaders(platform, 'process_instance_list', project, environment, { asUser, asUserId })
+    })));
+    server.registerTool('process_instance_get', {
+        title: 'Süreç örneğini getir',
+        description: "Örneği getirir. view:'timeline' defteri (sıralı olaylar, hash zinciri), güncel ve sonraki düğümleri ve isLedgerValid'i döner — zincir kırıksa defter kurcalanmıştır. view:'events' defteri CSV olarak verir (sequence, occurredAt, kind, nodeId, taskId, actorUserId, actorKind, payload, previousHash, hash; en çok 256 KB satır içi — büyükse zaman çizelgesini okuyun). view:'verify' hash zincirini doğrular: { isValid, brokenAtSequence, eventCount }. Arşivlenmiş örnek bu uçlarda 404 döner.",
+        inputSchema: {
+            project: projectParam,
+            environment: environmentParam,
+            id: guid,
+            view: z.enum(['summary', 'timeline', 'events', 'verify']).optional().describe('varsayılan summary'),
+            asUser: asUserParam,
+            asUserId: asUserIdBpmParam
+        },
+        annotations: readOnly
+    }, handle(config, async ({ project, environment, id, view, asUser, asUserId }) => {
+        const headers = await bpmIdentityHeaders(platform, 'process_instance_get', project, environment, { asUser, asUserId });
+        if (view === 'verify')
+            return platform.tenant('GET', project, `/bpm/instances/${id}/events/verify`, { environment, headers });
+        if (view === 'events') {
+            const payload = await platform.tenant('GET', project, `/bpm/instances/${id}/events`, { environment, query: { format: 'csv' }, expectBinary: true, headers });
+            if (payload.bytes.byteLength > maxInlineLedgerBytes) {
+                throw new PlatformApiError(`process_instance_get: defter CSV'si ${payload.bytes.byteLength} B, satır içi sınır ${maxInlineLedgerBytes} B; view:'timeline' ile okuyun ya da dosyayı uçtan (GET bpm/instances/${id}/events?format=csv) indirin.`, 413);
+            }
+            return { format: 'csv', sizeBytes: payload.bytes.byteLength, csv: payload.bytes.toString('utf8').replace(/^\uFEFF/, '') };
+        }
+        return platform.tenant('GET', project, view === 'timeline' ? `/bpm/instances/${id}/timeline` : `/bpm/instances/${id}`, { environment, headers });
+    }));
+    server.registerTool('process_instance_update', {
+        title: 'Süreç örneğine müdahale',
+        description: "Örneğe tek kapıdan müdahale: operation cancel | suspend (reason ZORUNLU; tanımda onCancel varsa önce telafi koşar, başarısızsa örnek faulted kalır ve iptal edilmez) | resume | withdraw (yalnız başlatan, withdrawPolicy; tanımdaki onCancel telafisi ve writeBack'i cancel.cause='withdrawn' ile koşar, açık görevler ve zamanlayıcılar kapanır) | reopen (bitiş düğümünün reopenWindow süresi içinde; nodeId opsiyonel) | retry (yalnız faulted; servis denemeleri sıfırlanır) | skip (nodeId'deki token düğümü tamamlanmış sayılıp ilerler, reason ZORUNLU, defterde node-skipped) | jump (nodeId → targetNodeId, reason ZORUNLU, atlanan görevler iptal, defterde instance-jumped) | watch / unwatch (karar ve kapanış bildirimlerini izle; taskId ile tek görev). Yetki process.manage (withdraw, watch hariç). production hedefi istek gitmeden durur (BPM-001).",
+        inputSchema: {
+            project: projectParam,
+            environment: environmentParam,
+            id: guid,
+            operation: z.enum(instanceOperations),
+            reason: z.string().max(1000).optional(),
+            nodeId: z.string().max(100).optional(),
+            targetNodeId: z.string().max(100).optional().describe('jump için'),
+            taskId: guid.optional().describe('watch / unwatch için tek görev'),
+            asUser: asUserParam,
+            asUserId: asUserIdBpmParam,
+            expectFailure: expectFailureParam
+        },
+        annotations: updates
+    }, handle(config, async ({ project, environment, id, operation, reason, nodeId, targetNodeId, taskId, asUser, asUserId }) => {
+        assertProcessNotProduction('process_instance_update', environment, config);
+        if ((operation === 'cancel' || operation === 'suspend' || operation === 'skip' || operation === 'jump') && !reason?.trim()) {
+            throw new PlatformApiError(`process_instance_update: '${operation}' gerekçe ister — 'reason' verin (platform reddeder, istek gönderilmedi).`, 400);
+        }
+        if (operation === 'jump' && !targetNodeId)
+            throw new PlatformApiError("process_instance_update: 'jump' targetNodeId ister (istek gönderilmedi).", 400);
+        if (operation === 'watch' || operation === 'unwatch') {
+            return platform.tenant(operation === 'watch' ? 'POST' : 'DELETE', project, `/bpm/instances/${id}/watch`, {
+                environment,
+                query: taskId ? { taskId } : undefined,
+                headers: await bpmIdentityHeaders(platform, 'process_instance_update', project, environment, { asUser, asUserId })
+            });
+        }
+        const bodies = {
+            reopen: { nodeId },
+            cancel: { reason },
+            suspend: { reason },
+            retry: { reason },
+            skip: { nodeId, reason },
+            jump: { fromNodeId: nodeId, targetNodeId, reason }
+        };
+        const body = bodies[operation] ?? {};
+        return platform.tenant('POST', project, `/bpm/instances/${id}/${operation}`, {
+            environment,
+            body,
+            headers: await bpmIdentityHeaders(platform, 'process_instance_update', project, environment, { asUser, asUserId })
+        });
+    }));
+    server.registerTool('process_task_list', {
+        title: 'Görev kutusunu listele',
+        description: "Kişinin görev kutusu: tab mine (atanan) | group (aday olduğu, üstlenilmemiş) | delegated | started (başlattığı süreçler) | done | all (process.view-all/manage) | planned (plannedStart'ı gelmemiş görevler). scope application (applicationId verilirse o uygulamanın görevleri) | realm (projedeki tüm uygulamalar; satırda applicationSlug rozeti). q doğal dil süzgecidir ('bu ay geciken satınalmalar'): platform AI ile { definition, overdue, from, to, minPriority } süzgecine çevirir, liste yine görünürlük kurallarıyla sorgulanır ve yanıtta appliedFilter döner (tanınmayan istek boş süzgeç; tahmin yok; dakikalık sınır aşılırsa 429 AiRateLimited). q dış AI modelini çağırır ve öneri tablosuna iz yazar; bu yüzden q ile production hedefi durur (BPM-001). asUser verilmezse gateway'in kendi kullanıcısının kutusu döner.",
+        inputSchema: {
+            project: projectParam,
+            environment: environmentParam,
+            tab: z.enum(['mine', 'group', 'delegated', 'started', 'done', 'all', 'planned']).optional().describe('varsayılan mine'),
+            scope: z.enum(['application', 'realm']).optional().describe('varsayılan application'),
+            applicationId: guid.optional(),
+            instanceId: guid.optional(),
+            q: z.string().min(1).max(500).optional().describe("doğal dil süzgeci, ör. 'bu ay geciken satınalmalar'; yanıtta appliedFilter"),
+            asUser: asUserParam,
+            asUserId: asUserIdBpmParam,
+            ...pagingParams
+        },
+        annotations: readOnly
+    }, handle(config, async ({ project, environment, asUser, asUserId, ...query }) => {
+        if (query.q)
+            assertProcessNotProduction('process_task_list', environment, config);
+        return platform.tenant('GET', project, '/bpm/tasks', { environment, query, headers: await bpmIdentityHeaders(platform, 'process_task_list', project, environment, { asUser, asUserId }) });
+    }));
+    server.registerTool('process_task_get', {
+        title: 'Görevi getir',
+        description: "Görevi, kullanılabilir eylemleriyle (actions) ve güncel 'version' değeriyle getirir. Görev eyleminden önce okuyun: claim/complete bayat version ile 409 AggregateVersionConflictException, başkasının üstlendiği görevde 409 TaskAlreadyClaimed alır. view 'assistant': görev yardımcısı — question yoksa özet (GET …/assistant/summary), varsa yanıt (POST …/assistant/ask); yanıt { aiSuggestion: { text, suggestedAction, rationale, similarOutcomes, promptHash, suggestionId } }. AI ÖNERİSİDİR, karar değildir: görevi kapatmaz, outcome yazmaz; kararı process_task_update ile kişi verir. Korumalı alanlar modele maskeli gider; her çağrı öneri tablosuna ve süreç defterine (ai-suggestion) iz yazar ve dakikalık sınıra sayılır (429 AiRateLimited); bu yüzden production hedefi durur (BPM-001). Aracın annotation'ı bu yan etki yüzünden readOnly değildir (katalogda bilinçli istisna).",
+        inputSchema: {
+            project: projectParam,
+            environment: environmentParam,
+            id: guid,
+            view: z.enum(['task', 'assistant']).optional().describe('varsayılan task'),
+            question: z.string().min(1).max(2000).optional().describe("yalnız view 'assistant': göreve dair soru"),
+            asUser: asUserParam,
+            asUserId: asUserIdBpmParam
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
+    }, handle(config, async ({ project, environment, id, view, question, asUser, asUserId }) => {
+        const headers = await bpmIdentityHeaders(platform, 'process_task_get', project, environment, { asUser, asUserId });
+        if (view !== 'assistant') {
+            if (question !== undefined)
+                throw new PlatformApiError("process_task_get: 'question' yalnız view: 'assistant' ile verilir (istek gönderilmedi).", 400);
+            return platform.tenant('GET', project, `/bpm/tasks/${id}`, { environment, headers });
+        }
+        assertProcessNotProduction('process_task_get', environment, config);
+        const assistant = question === undefined
+            ? await platform.tenant('GET', project, `/bpm/tasks/${id}/assistant/summary`, { environment, headers })
+            : await platform.tenant('POST', project, `/bpm/tasks/${id}/assistant/ask`, { environment, body: { question }, headers });
+        return { aiSuggestion: assistant.data ?? assistant, note: 'AI önerisi — karar değil; görev durumu değişmedi.' };
+    }));
+    server.registerTool('process_task_update', {
+        title: 'Görev eylemi',
+        description: "Görev eylemlerinin tek kapısı: action claim | unclaim | complete (actionId ile özel eylem; completes:false eylem görevi açık bırakıp sinyal yayar) | approve | reject | request-info (question) | provide-info (answer) | reassign (targetUserId, reason) | undo (undoWindow içinde) | sign (signature taşıyan düğüm: password ZORUNLU, düğüm signature.reauth:false değilse — BPM-018; meaning verilmezse düğümün anlamı, düğümde anlam yoksa projenin Bpm:SignatureMeanings sözlüğünden biri; asUser oturumundaki ilk imzada imzalayanın email'i de; fileId imzalanan belge, imzadan sonra dosya kilitlenir; 401 ReauthenticationRequired yeniden parola ister, 422 SignatureRequired imzasız tamamlama denemesidir) | start-assessment (assessment taşıyan user-task: soru bankasından deneme açar, yanıtta questions[] cevapsız; açık deneme varsa onu döner, hak bittiyse 422) | submit-assessment (answers { soruId: cevap }: puanlanır; geçerse okuma kanıtı eylemiyle görev kapanır, kalırsa hak varsa görev açık kalır, hak biterse sonuç assessment-failed; değerlendirmesiz okuma kanıtı 422 TaskStateTransitionNotAllowed). Parola gateway günlüğüne maskeli yazılır, yanıta girmez. asUser ZORUNLU (BPM-006): görev eylemi uygulama kullanıcısı adına yapılır, Studio jetonu 403 alır. version process_task_get'ten; 409 (TaskAlreadyClaimed ya da AggregateVersionConflictException) gelirse görevi yeniden okuyun. production hedefi durur (BPM-001).",
+        inputSchema: {
+            project: projectParam,
+            environment: environmentParam,
+            id: guid,
+            action: z.enum(taskActions),
+            actionId: z.string().max(100).optional().describe("complete için özel eylem id'si (tanımdaki actions[].id)"),
+            payload: z.record(z.unknown()).optional(),
+            comment: z.string().max(4000).optional(),
+            version: z.string().optional().describe("process_task_get yanıtındaki version METİN olarak (tick boyutlu sayı; number olarak gönderilirse yuvarlanır ve 409 alır)"),
+            targetUserId: z.string().max(64).optional(),
+            reason: z.string().max(1000).optional(),
+            question: z.string().max(4000).optional(),
+            answer: z.string().max(4000).optional(),
+            meaning: z.string().max(100).optional().describe("sign: imza anlamı (author | reviewer | approver | responsible | verifier ya da projede tanımlı)"),
+            email: z.string().max(200).optional().describe('sign: oturumdaki ilk imzada kullanıcı e-postası'),
+            password: z.string().max(200).optional().describe('sign: yeniden kimlik doğrulama parolası'),
+            fileId: guid.optional().describe('sign: imzalanan belge'),
+            answers: z.record(z.unknown()).optional().describe('submit-assessment: soru id → cevap'),
+            asUser: asUserParam,
+            asUserId: asUserIdBpmParam,
+            expectFailure: expectFailureParam
+        },
+        annotations: writes
+    }, handle(config, async ({ project, environment, id, action, actionId, payload, comment, version, targetUserId, reason, question, answer, meaning, email, password, fileId, answers, asUser, asUserId }) => {
+        assertProcessNotProduction('process_task_update', environment, config);
+        if (!asUser && !asUserId) {
+            throw new PolicyBlockError([{
+                    ruleId: 'BPM-006',
+                    severity: 'block',
+                    message: "process_task_update kimliksiz gönderilmez: görev eylemi bir uygulama kullanıcısı adına yapılır. İki yol var — development'ta parolasız 'asUserId' (users satır id'si, 'impersonated-user-id' başlığı) ya da 'asUser' (access_session_create ile giriş yapıp tokenRefs'teki tok_… değeri). /bpm/* uçları platform şemasıyla [Authorize] edildiği için uygulama jetonu 401 alabilir; parolasız yol asUserId'dir.",
+                    guide: 'ngapps://guides/bpm'
+                }]);
+        }
+        const payloadAnswers = payload?.answers;
+        if (action === 'submit-assessment') {
+            if (answers !== undefined && payloadAnswers !== undefined) {
+                throw new PlatformApiError("process_task_update: 'submit-assessment' cevapları ya 'answers' ya 'payload.answers' ile verilir, ikisi birden değil (istek gönderilmedi).", 400);
+            }
+            const submitted = answers ?? payloadAnswers;
+            if (!submitted || typeof submitted !== 'object' || Array.isArray(submitted) || Object.keys(submitted).length === 0) {
+                throw new PlatformApiError("process_task_update: 'submit-assessment' cevapsız gönderilmez — boş deneme 0 puan alır ve bir hak tüketir, son hakta görev assessment-failed ile kapanır. start-assessment yanıtındaki her soru id'si için answers { soruId: cevap } verin (istek gönderilmedi).", 400);
+            }
+        }
+        if (action === 'sign' && !password) {
+            const task = await platform.tenant('GET', project, `/bpm/tasks/${id}`, { environment, headers: await bpmIdentityHeaders(platform, 'process_task_update', project, environment, { asUser, asUserId }) });
+            if (task.data?.signature?.reauth !== false) {
+                throw new PolicyBlockError([{
+                        ruleId: 'BPM-018',
+                        severity: 'block',
+                        message: "process_task_update action 'sign' password olmadan gönderilmez: düğümün imzası (signature.reauth false değil) her seferinde imzalayanın parolasıyla yeniden kimlik doğrulaması ister (21 CFR 11.200); parolasız istek 401 ReauthenticationRequired döner ve imza girişimi kilit sayacına yazılır. meaning verilmezse düğümün anlamı kullanılır.",
+                        guide: 'ngapps://guides/bpm'
+                    }], false);
+            }
+        }
+        const bodies = {
+            claim: { version },
+            unclaim: {},
+            complete: { action: actionId ?? 'complete', payload, comment, version },
+            approve: { payload, comment, version },
+            reject: { payload, comment, version },
+            'request-info': { question },
+            'provide-info': { answer },
+            reassign: { targetUserId, reason },
+            undo: {},
+            sign: { meaning, email, password, fileId, comment, payload, version },
+            'start-assessment': {},
+            'submit-assessment': { action: 'submit-assessment', payload: { ...(payload ?? {}), answers: answers ?? payloadAnswers }, comment, version }
+        };
+        const paths = { 'start-assessment': 'assessment', 'submit-assessment': 'complete' };
+        return platform.tenant('POST', project, `/bpm/tasks/${id}/${paths[action] ?? action}`, {
+            environment,
+            body: bodies[action],
+            headers: await bpmIdentityHeaders(platform, 'process_task_update', project, environment, { asUser, asUserId })
+        });
+    }));
+    server.registerTool('process_preference_get', {
+        title: 'Bildirim tercihini getir',
+        description: 'Kullanıcının süreç bildirim tercihi: mode immediate | digest | sla-only, quietFrom/quietTo (sessiz saatler), digestAt (özet saati), timeZone, phone (sms kanalının alıcısı). Kayıt yoksa varsayılan (immediate, UTC) döner.',
+        inputSchema: { project: projectParam, environment: environmentParam, asUser: asUserParam, asUserId: asUserIdBpmParam },
+        annotations: readOnly
+    }, handle(config, async ({ project, environment, asUser, asUserId }) => platform.tenant('GET', project, '/bpm/notification-preferences', { environment, headers: await bpmIdentityHeaders(platform, 'process_preference_get', project, environment, { asUser, asUserId }) })));
+    server.registerTool('process_preference_update', {
+        title: 'Bildirim tercihini kaydet',
+        description: "Bildirim tercihini tam gövdeyle kaydeder: verilmeyen quietFrom/quietTo sessiz saati kaldırır. digest: bildirimler digestAt saatinde tek e-postada toplanır; sla-only: yalnız SLA hatırlatma/ihlal bildirimleri anında gider, diğerleri özete düşer. Sessiz saat her kategoriye uygulanır ve gönderimi pencere sonuna erteler. Saatler '08:00' ya da '08:00:00'. phone: notify düğümünün 'sms' kanalı bu numaraya gider (+905551112233; sağlayıcı kasadaki notification-sms kimliğinin bağlayıcısı, netgsm ya da twilio). teams ve slack kanalları kullanıcının e-postasıyla gider (notification-teams, notification-slack kimlikleri).",
+        inputSchema: {
+            project: projectParam,
+            environment: environmentParam,
+            mode: z.enum(['immediate', 'digest', 'sla-only']),
+            quietFrom: z.string().regex(/^\d{2}:\d{2}(:\d{2})?$/).optional(),
+            quietTo: z.string().regex(/^\d{2}:\d{2}(:\d{2})?$/).optional(),
+            digestAt: z.string().regex(/^\d{2}:\d{2}(:\d{2})?$/).optional(),
+            timeZone: z.string().min(1).max(100),
+            phone: z.string().regex(/^[+]?[0-9]{10,15}$/).optional().describe('sms kanalı alıcısı, ülke koduyla; verilmezse numara silinir'),
+            asUser: asUserParam,
+            asUserId: asUserIdBpmParam
+        },
+        annotations: updates
+    }, handle(config, async ({ project, environment, mode, quietFrom, quietTo, digestAt, timeZone, phone, asUser, asUserId }) => {
+        assertProcessNotProduction('process_preference_update', environment, config);
+        const seconds = (value) => value && /^\d{2}:\d{2}$/.test(value) ? `${value}:00` : value;
+        return platform.tenant('PUT', project, '/bpm/notification-preferences', {
+            environment,
+            body: { mode, quietFrom: seconds(quietFrom), quietTo: seconds(quietTo), digestAt: seconds(digestAt), timeZone, phone },
+            headers: await bpmIdentityHeaders(platform, 'process_preference_update', project, environment, { asUser, asUserId })
+        });
+    }));
+    server.registerTool('process_document_execute', {
+        title: 'Belge üret / damgala / bas',
+        description: "operation generate (varsayılan; POST bpm/documents/generate): DOCX şablonundan (templateFileId, {{alan}} ve {{a.b}} yer tutucuları, table belge sonuna tablo ekler) docx | pdf | html belge üretir ve files'a yazar; stamp (POST bpm/documents/{fileId}/stamp): revizyon/durum başlığı ve filigran basar; print (POST bpm/documents/{fileId}/print): 'KONTROLSÜZ KOPYA' damgalı basım kopyası üretir, instanceId + nodeId verilirse defter document-printed yazar. Yanıt dosya { id, name, extension, size, folderId }; indirmek için file_download. Süreç içinde aynı iş document düğümüdür.",
+        inputSchema: {
+            project: projectParam,
+            environment: environmentParam,
+            operation: z.enum(documentOperations).optional(),
+            templateFileId: guid.optional().describe('generate: DOCX şablonu'),
+            data: z.record(z.unknown()).optional().describe('generate: yer tutucu değerleri'),
+            format: z.enum(['docx', 'pdf', 'html']).optional().describe('generate: varsayılan docx'),
+            table: z.record(z.unknown()).optional().describe("generate: { headers: ['Kalem', 'Tutar'], rows: [['Vida', '12']] }"),
+            stamp: z.record(z.unknown()).optional().describe('generate: { revision, state, watermark, note }'),
+            fileName: z.string().max(200).optional(),
+            folderId: guid.optional(),
+            fileId: guid.optional().describe('stamp ve print: hedef dosya'),
+            revision: z.string().max(50).optional().describe('stamp'),
+            state: z.string().max(50).optional().describe('stamp'),
+            watermark: z.string().max(100).optional().describe('stamp'),
+            instanceId: guid.optional().describe('print: defter kaydı için örnek'),
+            nodeId: z.string().max(100).optional().describe('print: defter kaydı için düğüm')
+        },
+        annotations: writes
+    }, handle(config, async ({ project, environment, operation, templateFileId, data, format, table, stamp, fileName, folderId, fileId, revision, state, watermark, instanceId, nodeId }) => {
+        assertProcessNotProduction('process_document_execute', environment, config);
+        const resolvedOperation = operation ?? 'generate';
+        if (resolvedOperation === 'generate') {
+            if (!templateFileId)
+                throw new PlatformApiError("process_document_execute: generate templateFileId ister (istek gönderilmedi).", 400);
+            return platform.tenant('POST', project, '/bpm/documents/generate', { environment, body: { templateFileId, data, format, table, stamp, fileName, folderId } });
+        }
+        if (!fileId)
+            throw new PlatformApiError(`process_document_execute: ${resolvedOperation} fileId ister (istek gönderilmedi).`, 400);
+        return resolvedOperation === 'stamp'
+            ? platform.tenant('POST', project, `/bpm/documents/${fileId}/stamp`, { environment, body: { revision, state, watermark } })
+            : platform.tenant('POST', project, `/bpm/documents/${fileId}/print`, { environment, body: { instanceId, nodeId } });
+    }));
+}

package/dist/tools/case.js

@@ -0,0 +1,178 @@
+import { guid, projectParam, environmentParam, pagingParams, readOnly, writes, updates, destructive, microOps } from './common.js';
+import { applyPolicyMode, attachFindings, PolicyBlockError } from '../knowledge/policy.js';
+import { assertInline, writeLocalFile } from './bpmGovernance.js';
+import { assertProcessNotProduction, dataOf } from './bpm.js';
+import { resolvePatchOperations } from '../knowledge/outlines.js';
+import { withNormalization } from '../knowledge/normalize.js';
+import { PlatformApiError } from '../platform/errors.js';
+import { caseFindings } from '../knowledge/case.js';
+import { handle } from '../platform/responses.js';
+import { readFile } from 'node:fs/promises';
+import fastJsonPatch from 'fast-json-patch';
+import { resolve } from 'node:path';
+import { z } from 'zod';
+const maxInlineXmlBytes = 256_000;
+const maxCmmnBytes = 5_000_000;
+const caseParam = z.record(z.unknown())
+    .describe("Vaka modeli (CMMN 1.1): { slug, name, description, caseFile[{ id, default }], planItems[{ id, type: stage | human-task | milestone, parent, required, repeatable, manualActivation, discretionary, autoComplete (stage), assignee { rule: user | role | initiator, arg }, entry[], exit[] }], sentries[{ id, onParts[{ source, event: complete | start | terminate | occur | update }], ifPart }] }. Ayrıntı platform_guide('case').");
+const policyOverrideParam = z.boolean().optional()
+    .describe("true: politika block bulgularını warn'a indirir (bilinçli istisna; yanıtta işaretlenir)");
+const patchOperationsParam = z.array(z.record(z.unknown())).min(1)
+    .describe("RFC 6902 JSON Patch işlemleri, yollar vaka modeline göre. Öğe hedeflerken İNDEKS YERİNE SEÇİCİ: { op: 'replace', path: '/planItems[id=hukuk-gorusu]/assignee/arg', value: 'hukuk' }; yeni öğe '/planItems/-'.");
+function lintCase(config, caseModel, policyOverride) {
+    if (config.policyMode === 'off')
+        return [];
+    const findings = applyPolicyMode(config, caseFindings(caseModel), policyOverride === true);
+    const blocking = findings.filter(finding => finding.severity === 'block');
+    if (blocking.length > 0)
+        throw new PolicyBlockError(blocking);
+    return findings;
+}
+export function registerCaseTools(server, platform) {
+    const config = platform.config;
+    server.registerTool('case_definition_list', {
+        title: 'Vaka tanımlarını listele',
+        description: "CMMN vaka tanımlarını listeler (GET bpm/cases): slug, ad, aktif ve taslak sürüm numarası. Vaka yapılandırılmamış iş içindir (şikâyet, soruşturma); akış belli ise süreç tanımı (process_definition_*). Süreçten vaka 'case' düğümüyle başlar.",
+        inputSchema: { project: projectParam, environment: environmentParam, searchTerm: z.string().max(200).optional(), applicationId: guid.optional(), ...pagingParams },
+        annotations: readOnly
+    }, handle(config, ({ project, environment, ...query }) => platform.tenant('GET', project, '/bpm/cases', { environment, query })));
+    server.registerTool('case_definition_get', {
+        title: 'Vaka tanımını getir',
+        description: "Vaka tanımını getirir (GET bpm/cases/{id}): case güncel model (taslak varsa taslak), activeCase yayındaki model, versions[] (draft → active → retiring). CMMN XML için case_cmmn_get.",
+        inputSchema: { project: projectParam, environment: environmentParam, id: guid },
+        annotations: readOnly
+    }, handle(config, ({ project, environment, id }) => platform.tenant('GET', project, `/bpm/cases/${id}`, { environment })));
+    server.registerTool('case_definition_create', {
+        title: 'Vaka tanımı oluştur',
+        description: "Yeni vaka tanımı yazar (POST bpm/cases; taslak sürüm). İlk kullanımdan önce platform_guide('case') okuyun. Gateway yazmadan önce CASE-001'i denetler (tanımsız plan öğesine/vaka dosyasına bakan onPart ya da tanımsız entry/exit sentry'si, block); backend diğer kuralları 422 CaseInvalid bulgu listesiyle döner. Yayın case_definition_publish, başlatma case_execute.",
+        inputSchema: { project: projectParam, environment: environmentParam, applicationId: guid.optional(), case: caseParam, policyOverride: policyOverrideParam },
+        annotations: writes
+    }, handle(config, async ({ project, environment, applicationId, case: caseModel, policyOverride }) => {
+        assertProcessNotProduction('case_definition_create', environment, config);
+        const findings = lintCase(config, caseModel, policyOverride);
+        return attachFindings(dataOf(await platform.tenant('POST', project, '/bpm/cases', { environment, body: { applicationId, case: caseModel } })), findings);
+    }));
+    server.registerTool('case_definition_update', {
+        title: 'Vaka tanımını güncelle',
+        description: "Vaka tanımının taslağını tam modelle yazar (PUT bpm/cases/{id}; taslak yoksa yeni sürüm numarası açılır). Backend sürüm denetimi yapmaz: son yazan kazanır; hedefli değişiklik için case_definition_patch. İlk yayından sonra slug değişmez (400). CASE-001 denetimi case_definition_create ile aynı.",
+        inputSchema: { project: projectParam, environment: environmentParam, id: guid, case: caseParam, policyOverride: policyOverrideParam },
+        annotations: updates
+    }, handle(config, async ({ project, environment, id, case: caseModel, policyOverride }) => {
+        assertProcessNotProduction('case_definition_update', environment, config);
+        const findings = lintCase(config, caseModel, policyOverride);
+        return attachFindings(dataOf(await platform.tenant('PUT', project, `/bpm/cases/${id}`, { environment, body: { case: caseModel } })), findings);
+    }));
+    server.registerTool('case_definition_patch', {
+        title: 'Vaka tanımına patch uygula',
+        description: "Tam modeli bağlama almadan hedefli değişiklik: gateway güncel modeli okur (GET), seçicileri (/planItems[id=x], /sentries[id=x], /caseFile[id=x]) çözer, yamayı yerelde uygular, CASE-001'den geçirir ve tam modeli taslağa yazar (PUT). Backend sürüm denetimi yok: okuma ile yazma arasında başka yazan olursa değişikliği ezilir. Yanıt { patchTargets, case }.",
+        inputSchema: {
+            project: projectParam,
+            environment: environmentParam,
+            id: guid,
+            operations: patchOperationsParam.optional(),
+            ops: patchOperationsParam.optional().describe("'operations' ile aynı alan (eşanlamlı)"),
+            policyOverride: policyOverrideParam
+        },
+        annotations: updates
+    }, handle(config, async ({ project, environment, id, operations: givenOperations, ops, policyOverride }) => {
+        assertProcessNotProduction('case_definition_patch', environment, config);
+        const operations = microOps('case_definition_patch', ops, givenOperations);
+        const current = dataOf(await platform.tenant('GET', project, `/bpm/cases/${id}`, { environment }));
+        const model = structuredClone((current.case ?? {}));
+        const resolved = resolvePatchOperations(model, operations, 'case_definition_get');
+        let patched;
+        try {
+            patched = fastJsonPatch.applyPatch(model, resolved.operations, true, false).newDocument;
+        }
+        catch (error) {
+            throw new PlatformApiError(`case_definition_patch: yama uygulanamadı — ${error instanceof Error ? error.message : String(error)} (istek gönderilmedi). Yolları case_definition_get çıktısına göre kurun.`, 400);
+        }
+        const findings = lintCase(config, patched, policyOverride);
+        const saved = dataOf(await platform.tenant('PUT', project, `/bpm/cases/${id}`, { environment, body: { case: patched } }));
+        return withNormalization(attachFindings({ patchTargets: resolved.targets, case: saved.case ?? patched }, findings), resolved.notes);
+    }));
+    server.registerTool('case_definition_delete', {
+        title: 'Vaka tanımını sil',
+        description: "Vaka tanımını ve sürümlerini siler (DELETE bpm/cases/{id}). Bir süreç tanımının 'case' düğümü başvuruyorsa 422 ReferencedByProcess; herhangi bir vakası (açık ya da kapalı) varsa 400 InvalidOperation.",
+        inputSchema: { project: projectParam, environment: environmentParam, id: guid },
+        annotations: destructive
+    }, handle(config, async ({ project, environment, id }) => {
+        assertProcessNotProduction('case_definition_delete', environment, config);
+        return platform.tenant('DELETE', project, `/bpm/cases/${id}`, { environment });
+    }));
+    server.registerTool('case_definition_preview', {
+        title: 'Vaka modelini denetle (kuru)',
+        description: "Vaka modelini YAN ETKİSİZ ve İSTEK GÖNDERMEDEN gateway kurallarıyla denetler (platform_guide('case') §Model) (CASE-001: onPart/entry/exit başvuruları). Yanıt { valid, policyFindings }. Backend'de ayrı doğrulama ucu yoktur: kalan kurallar (kebab-case kimlik, parent döngüsü, human-task assignee, repeatable için giriş sentry'si, onPart olay türü) case_definition_create/update yazımında 422 CaseInvalid bulgu listesiyle döner.",
+        inputSchema: { case: caseParam },
+        annotations: readOnly
+    }, handle(config, async ({ case: caseModel }) => {
+        const findings = caseFindings(caseModel);
+        return { valid: !findings.some(finding => finding.severity === 'block'), policyFindings: findings };
+    }));
+    server.registerTool('case_definition_publish', {
+        title: 'Vaka tanımını yayınla',
+        description: "Taslağı aktif sürüm yapar (POST bpm/cases/{id}/publish); önceki aktif sürüm retiring olur, çalışan vakalar başladıkları sürümde kalır. Gateway yayından önce taslağı CASE-001 ile denetler. production hedefi durur (BPM-001).",
+        inputSchema: { project: projectParam, environment: environmentParam, id: guid, policyOverride: policyOverrideParam },
+        annotations: writes
+    }, handle(config, async ({ project, environment, id, policyOverride }) => {
+        assertProcessNotProduction('case_definition_publish', environment, config);
+        const current = dataOf(await platform.tenant('GET', project, `/bpm/cases/${id}`, { environment }));
+        const findings = lintCase(config, (current.case ?? {}), policyOverride);
+        return attachFindings(dataOf(await platform.tenant('POST', project, `/bpm/cases/${id}/publish`, { environment })), findings);
+    }));
+    server.registerTool('case_cmmn_get', {
+        title: 'Vaka tanımını CMMN 1.1 XML olarak dışa aktar',
+        description: "Vaka tanımını CMMN 1.1 XML'e çevirir (GET bpm/cases/{id}/cmmn; zeyrek: uzantısı atamayı, çok dilli ad/açıklamayı, vaka dosyası varsayılanını ve sırayı taşır): taslak, yoksa aktif, yoksa son sürüm. Yanıt { caseId, versionNumber, state, sizeBytes, xml }; 256 KB üstü için outPath verin.",
+        inputSchema: {
+            project: projectParam,
+            environment: environmentParam,
+            id: guid,
+            outPath: z.string().min(1).optional().describe('verilirse XML bu yerel yola yazılır ve yanıt yalnız özet döner')
+        },
+        annotations: readOnly
+    }, handle(config, async ({ project, environment, id, outPath }) => {
+        const response = await platform.tenantWithHeaders('GET', project, `/bpm/cases/${id}/cmmn`, { environment, expectBinary: true });
+        const payload = response.body;
+        const xml = payload.bytes.toString('utf8').replace(/^/, '');
+        const summary = {
+            caseId: id,
+            versionNumber: Number(response.headers['x-case-version']) || null,
+            state: response.headers['x-case-version-state'] ?? null,
+            sizeBytes: payload.bytes.byteLength
+        };
+        if (outPath)
+            return { ...summary, path: await writeLocalFile('case_cmmn_get', outPath, xml) };
+        const inline = { ...summary, xml };
+        assertInline('case_cmmn_get', config, inline);
+        return inline;
+    }));
+    server.registerTool('case_cmmn_update', {
+        title: 'CMMN 1.1 XML içe aktar',
+        description: "CMMN 1.1 XML'deki vakayı içe aktarır (POST bpm/cases/import-cmmn): case id'si (slug) mevcut tanımın taslağına yazılır, yoksa yeni tanım oluşur. xml (≤ 256 KB) ya da filePath (≤ 5 MB) — biri. stage/humanTask/milestone dışı plan öğesi (processTask, caseTask, event listener), çözülmeyen başvuru ve DTD/dış varlık içeren XML 400 InvalidParameter; model kuralları 422 CaseInvalid.",
+        inputSchema: {
+            project: projectParam,
+            environment: environmentParam,
+            applicationId: guid.optional(),
+            xml: z.string().min(1).max(maxInlineXmlBytes).optional(),
+            filePath: z.string().min(1).optional().describe('yerel .cmmn dosyası')
+        },
+        annotations: updates
+    }, handle(config, async ({ project, environment, applicationId, xml, filePath }) => {
+        assertProcessNotProduction('case_cmmn_update', environment, config);
+        if (Boolean(xml) === Boolean(filePath))
+            throw new PlatformApiError("case_cmmn_update: 'xml' ya da 'filePath' — yalnız biri (istek gönderilmedi).", 400);
+        let content = xml ?? '';
+        if (filePath) {
+            try {
+                content = await readFile(resolve(filePath), 'utf8');
+            }
+            catch (error) {
+                throw new PlatformApiError(`case_cmmn_update: dosya okunamadı — ${resolve(filePath)} (${error instanceof Error ? error.message : String(error)}). Yol gateway sürecinin çalıştığı makineye göre çözülür (istek gönderilmedi).`, 400);
+            }
+        }
+        content = content.replace(/^/, '');
+        if (Buffer.byteLength(content, 'utf8') > maxCmmnBytes)
+            throw new PlatformApiError(`case_cmmn_update: XML en çok ${maxCmmnBytes} B (istek gönderilmedi).`, 413);
+        return platform.tenant('POST', project, '/bpm/cases/import-cmmn', { environment, body: { applicationId, xml: content } });
+    }));
+}