engineering-memory 1.11.18 → 1.11.20

package/runtime/dist/src/mcp/workflow-tools.js

@@ -0,0 +1,401 @@
+import * as z from 'zod/v4';
+import { languageTag } from '../runtime/questionnaire-store.js';
+import { sha256, stableStringify } from '../utilities/hash.js';
+import { answerChoice, askQuestionnaire } from './questionnaire-tools.js';
+import { assertSafeToPersist } from '../runtime/offline-outbox.js';
+const role = z.enum([
+    'work_started',
+    'pr_opened',
+    'all_prs_merged',
+    'test_failed',
+    'blocked_declared',
+]);
+const mode = z.enum(['automatic', 'confirm', 'ignore']);
+const navigation = z.tuple([z.string().trim().min(1).max(120), z.string().trim().min(1).max(400)]);
+const wording = z
+    .object({
+    roles: z.record(role, z
+        .object({
+        title: z.string().trim().min(1).max(60),
+        message: z.string().trim().min(1).max(300),
+        context: z.string().trim().min(1).max(600),
+        example: z.string().trim().min(1).max(400),
+    })
+        .strict()),
+    modes: z.record(mode, z.string().trim().min(1).max(80)),
+    page: z.string().trim().min(1).max(80),
+    next: navigation,
+    previous: navigation,
+    defer: navigation,
+    approve: navigation,
+    review: z
+        .object({
+        message: z.string().trim().min(1).max(300),
+        context: z.string().trim().min(1).max(400),
+        example: z.string().trim().min(1).max(400),
+    })
+        .strict(),
+})
+    .strict();
+const setupInput = z
+    .object({
+    repoRoot: z.string().min(1),
+    projectId: z.string().uuid(),
+    externalTaskId: z.string().trim().min(2).max(160),
+    requestKey: z.string().regex(/^[A-Za-z0-9_-]{1,80}$/),
+    expectedSnapshot: z.string().regex(/^[a-f0-9]{64}$/),
+    recommendations: z
+        .array(z
+        .object({
+        event: role,
+        statusId: z.string().uuid(),
+        mode,
+        reason: z.string().trim().min(1).max(200),
+    })
+        .strict())
+        .length(5)
+        .refine((values) => new Set(values.map((value) => value.event)).size === 5),
+    language: languageTag,
+    copy: wording.optional(),
+    decisionAttempt: z.number().int().min(1).max(10000).optional(),
+    presentation: z.literal('host_native').optional(),
+})
+    .strict();
+const stage = z.object({
+    id: z.string().uuid(),
+    name: z.string().min(1).max(120),
+    slug: z.string().min(1).max(64),
+    meaning: z.string().max(4000),
+    archivedAt: z.string().nullable(),
+});
+const workflowPage = z.object({
+    snapshot: z.string().regex(/^[a-f0-9]{64}$/),
+    items: z.array(stage).max(100),
+    total: z.number().int().min(0),
+    offset: z.number().int().min(0),
+    limit: z.number().int().min(1).max(100),
+});
+const copy = {
+    tr: {
+        roles: {
+            work_started: {
+                title: 'Geliştirme',
+                message: 'Geliştirmeye başlayınca hangi kolon kullanılsın?',
+                context: 'Yeni işin açıldığı kolondan ayrı olarak, geliştirmeye başlama adımını ayarlıyoruz.',
+                example: 'Ödeme hatasını düzeltmeye başladığında kullanılacak kolonu seçiyorsun.',
+            },
+            pr_opened: {
+                title: 'İncelemeye hazır PR',
+                message: 'PR incelemeye hazır olunca hangi kolon kullanılsın?',
+                context: 'Taslak PR davranışı aynı kalır; burada incelemeye hazır PR adımını ayarlıyoruz.',
+                example: 'Değişikliğini bitirip ekip arkadaşının incelemesine açtığında kullanılacak kolon.',
+            },
+            all_prs_merged: {
+                title: 'Bütün PR’lar birleşti',
+                message: 'İşin bütün PR’ları birleşince hangi kolon kullanılsın?',
+                context: 'Bu işe bağlı bütün PR’ların birleştiği adımı ayarlıyoruz.',
+                example: 'Hem web hem sunucu değişiklikleri birleştirildiğinde kullanılacak kolon.',
+            },
+            test_failed: {
+                title: 'Başarısız test',
+                message: 'Test başarısız olunca hangi kolon kullanılsın?',
+                context: 'Başarısız testin ardından yapılacak düzeltmeler için kolon seçiyoruz.',
+                example: 'Ödeme testinde hata bulundu; düzeltme bekleyen iş için kullanılacak kolon.',
+            },
+            blocked_declared: {
+                title: 'Park edilen işler',
+                message: 'Beklemeye alınan işler hangi kolonda park edilsin?',
+                context: 'Projenin aktif park kolonunu seçiyoruz; mevcut işler yerinde kalacak.',
+                example: 'Dış servisten yanıt beklediğin için işi beklemeye aldığında kullanılacak kolon.',
+            },
+        },
+        modes: { automatic: 'Otomatik', confirm: 'Onay sor', ignore: 'Olayı dikkate alma' },
+        page: 'Sayfa',
+        next: ['Sonraki kolonlar', 'Aynı kararın sonraki kolonlarını göster.'],
+        previous: ['Önceki kolonlar', 'Aynı kararın önceki kolonlarına dön.'],
+        defer: ['Şimdi kaydetme', 'Seçimleri uygulama; bu deneme ertelenmiş olarak kalır.'],
+        approve: [
+            'Bu ayarları kaydet',
+            'Gösterilen beş tercihi birlikte kaydet; mevcut işleri taşıma.',
+        ],
+        review: {
+            message: 'Bu akış ayarlarını birlikte kaydedelim mi?',
+            context: 'Beş kolon ve davranış aşağıda. Taslak PR ve yeni işin başlangıç kolonu değişmez. Bu işlem yalnızca ayarları kaydeder; olay çalıştırmaz.',
+            example: 'Beklemeye alınan işler için Beklemede kolonunu seçtiysen proje bundan sonra bu tercihi saklar; önceki işler yerinde kalır.',
+        },
+    },
+    en: {
+        roles: {
+            work_started: {
+                title: 'Development',
+                message: 'Which stage should represent starting development?',
+                context: 'This is separate from the stage where new work is created.',
+                example: 'Choose the stage used when you begin fixing a payment bug.',
+            },
+            pr_opened: {
+                title: 'PR ready for review',
+                message: 'Which stage should represent a PR ready for review?',
+                context: 'Draft PR behavior stays unchanged; this configures the ready-for-review step.',
+                example: 'Use this stage when your completed change is ready for a teammate to review.',
+            },
+            all_prs_merged: {
+                title: 'All PRs merged',
+                message: 'Which stage should represent all PRs being merged?',
+                context: 'This configures the step after every PR belonging to the work has merged.',
+                example: 'Both the web change and its backend change have been merged.',
+            },
+            test_failed: {
+                title: 'Failed test',
+                message: 'Which stage should represent a failed test?',
+                context: 'Choose the stage for work that needs changes after a failed test.',
+                example: 'A payment test found a problem and the work needs a correction.',
+            },
+            blocked_declared: {
+                title: 'Parked work',
+                message: 'Which stage should hold parked work?',
+                context: 'Choose the active parked stage; existing work stays where it is.',
+                example: 'You put a task on hold while waiting for an external service.',
+            },
+        },
+        modes: { automatic: 'Automatic', confirm: 'Ask for approval', ignore: 'Ignore this event' },
+        page: 'Page',
+        next: ['Next stages', 'Show the next stages for this same decision.'],
+        previous: ['Previous stages', 'Return to the previous stages for this same decision.'],
+        defer: ['Do not save now', 'Apply nothing; this attempt remains deferred.'],
+        approve: [
+            'Save these settings',
+            'Save the five displayed choices together without moving existing work.',
+        ],
+        review: {
+            message: 'Save these workflow settings together?',
+            context: 'The five stages and behaviors appear below. Draft PR and new-work initial settings stay unchanged. This saves configuration only; no event is executed.',
+            example: 'Choosing On Hold for parked work stores that preference for the project; earlier tasks remain in place.',
+        },
+    },
+};
+function stageQuestion(input, text, language, stages, recommendation, setupId, selected, page, visit) {
+    const recommended = stages.find((item) => item.id === recommendation.statusId);
+    const others = stages.filter((item) => item.id !== recommendation.statusId);
+    const visible = [recommended, ...others.slice(page * 8, page * 8 + 8)];
+    const count = Math.max(1, Math.ceil(others.length / 8));
+    const question = text.roles[recommendation.event];
+    const options = visible.map((item) => ({
+        id: item.id,
+        label: item.name + ' (' + item.slug + ')',
+        description: [
+            text.modes[recommendation.mode],
+            item.id === recommendation.statusId ? recommendation.reason : '',
+            item.meaning,
+        ]
+            .filter(Boolean)
+            .join(' · ')
+            .slice(0, 400),
+    }));
+    if (page > 0)
+        options.push({ id: 'previous', label: text.previous[0], description: text.previous[1] });
+    if (page + 1 < count)
+        options.push({ id: 'next', label: text.next[0], description: text.next[1] });
+    options.push({ id: 'defer', label: text.defer[0], description: text.defer[1] });
+    return {
+        questionnaireId: 'workflow-role-' +
+            sha256(stableStringify({ setupId, selected, event: recommendation.event, page, visit })),
+        language,
+        impact: 'critical',
+        message: question.message,
+        context: question.context + ' ' + text.page + ' ' + (page + 1) + '/' + count + '.',
+        example: question.example,
+        options,
+        binding: {
+            setupId,
+            projectId: input.projectId,
+            expectedSnapshot: input.expectedSnapshot,
+            event: recommendation.event,
+            mode: recommendation.mode,
+            page,
+            visit,
+        },
+    };
+}
+export function registerWorkflowTools(server, service) {
+    server.registerTool('work_item.setup_workflow', {
+        description: 'Review five project workflow roles in durable native forms and save them together. First read work_item.workflow and supply its exact snapshot plus five deliberate recommendations, explicit modes and reasons in the user language. The current task must be resumed in this repository. All active stages are reachable through pages; existing work and draft PR settings stay unchanged. Questions are critical and follow the task mode; feedback is not consent. Retry identical input to resume. After deferral or a mode-invalidated agent answer, use a new decisionAttempt only when reconsideration is authorized. Use copy for languages other than Turkish/English; translate every field. Never silently replace a stale snapshot. This does not fire events.',
+        inputSchema: setupInput,
+    }, async (input, context) => setupWorkflow(server, service, input, context));
+}
+async function setupWorkflow(server, service, input, context) {
+    const scope = await service.workItemSetupContext(input);
+    if (!scope.ok)
+        return output(scope);
+    const { repoRoot: _repoRoot, ...retryArguments } = input;
+    try {
+        assertSafeToPersist(retryArguments, '', '', true);
+    }
+    catch {
+        return refusal('Remove sensitive content from the workflow question and its retry arguments before continuing.', 'work_item.setup_workflow');
+    }
+    const language = input.language ?? (await service.language());
+    if (!language)
+        return refusal('Read session.entry with the conversation language first.', 'session.entry');
+    const baseLanguage = language.split('-')[0];
+    const text = input.copy ?? (baseLanguage === 'tr' || baseLanguage === 'en' ? copy[baseLanguage] : undefined);
+    if (!text)
+        return refusal('Supply every copy field in the conversation language, preserving this snapshot and requestKey.', 'work_item.setup_workflow');
+    const stages = [];
+    let total;
+    for (let offset = 0; total === undefined || offset < total; offset += 100) {
+        const response = await service.workItemWorkflow({
+            projectId: input.projectId,
+            snapshot: input.expectedSnapshot,
+            limit: 100,
+            offset,
+        });
+        if (!response.ok)
+            return output(response);
+        const parsed = workflowPage.safeParse(response.data);
+        if (!parsed.success)
+            return refusal('The workflow response is incomplete. Reload its contract before opening choices.', 'work_item.workflow');
+        const page = parsed.data;
+        if (page.snapshot !== input.expectedSnapshot ||
+            page.offset !== offset ||
+            page.limit !== 100 ||
+            (total !== undefined && page.total !== total) ||
+            page.items.some((item) => item.archivedAt !== null) ||
+            page.items.length !== Math.min(100, Math.max(0, page.total - offset)))
+            return refusal('The workflow pages changed or were incomplete. Reload every page before reviewing choices.', 'work_item.workflow');
+        total = page.total;
+        stages.push(...page.items);
+    }
+    if (new Set(stages.map((item) => item.id)).size !== stages.length ||
+        input.recommendations.some((entry) => !stages.some((item) => item.id === entry.statusId)))
+        return refusal('Each recommendation must name an active stage from this complete project workflow.', 'work_item.workflow');
+    const setupId = sha256(stableStringify({
+        namespace: scope.data.namespace,
+        projectId: input.projectId,
+        externalTaskId: input.externalTaskId,
+        requestKey: input.requestKey,
+        snapshot: input.expectedSnapshot,
+        recommendations: input.recommendations,
+        decisionAttempt: input.decisionAttempt ?? 0,
+        language,
+        copy: text,
+    }));
+    const owner = {
+        tool: 'work_item.setup_workflow',
+        externalTaskId: input.externalTaskId,
+        decisionAttempt: input.decisionAttempt,
+        retryArguments,
+    };
+    const selected = [];
+    const selectionQuestionnaireIds = [];
+    for (const event of role.options) {
+        const recommendation = input.recommendations.find((entry) => entry.event === event);
+        let page = 0;
+        let visit = 0;
+        for (;;) {
+            if (context.mcpReq.signal.aborted)
+                return output({ ok: true, data: { status: 'pending', reason: 'interrupted' } });
+            const question = stageQuestion(input, text, language, stages, recommendation, setupId, selected, page, visit);
+            const answer = await askQuestionnaire(server, service, { ...question, repoRoot: input.repoRoot, presentation: input.presentation }, context, [], owner);
+            const choice = answerChoice(answer);
+            if (!choice)
+                return answer;
+            if (choice === 'defer')
+                return deferred(input);
+            if (choice === 'next' || choice === 'previous') {
+                page += choice === 'next' ? 1 : -1;
+                visit++;
+                continue;
+            }
+            if (!question.options.some((option) => option.id === choice) ||
+                !stages.some((item) => item.id === choice))
+                return refusal('The selected stage does not belong to this exact question.', 'questionnaire.resume');
+            selected.push({ event, toStatusId: choice, mode: recommendation.mode });
+            selectionQuestionnaireIds.push(question.questionnaireId);
+            break;
+        }
+    }
+    const proposal = {
+        projectId: input.projectId,
+        expectedSnapshot: input.expectedSnapshot,
+        rules: selected,
+    };
+    const proposalDigest = sha256(stableStringify(proposal));
+    const questionnaireId = 'workflow-apply-' +
+        sha256(stableStringify({ setupId, proposalDigest, selectionQuestionnaireIds }));
+    const review = {
+        questionnaireId,
+        language,
+        impact: 'critical',
+        context: text.review.context,
+        message: text.review.message +
+            '\n' +
+            selected
+                .map((item) => {
+                const target = stages.find((entry) => entry.id === item.toStatusId);
+                return (text.roles[item.event].title +
+                    ' ' +
+                    target.name +
+                    ' (' +
+                    target.slug +
+                    ') · ' +
+                    text.modes[item.mode]);
+            })
+                .join('\n'),
+        example: text.review.example,
+        options: [
+            { id: 'approve', label: text.approve[0], description: text.approve[1] },
+            { id: 'defer', label: text.defer[0], description: text.defer[1] },
+        ],
+        binding: {
+            setupId,
+            proposalDigest,
+            selectionQuestionnaireIds,
+            namespace: scope.data.namespace,
+        },
+    };
+    const approval = await askQuestionnaire(server, service, { ...review, repoRoot: input.repoRoot, presentation: input.presentation }, context, [], owner);
+    if (answerChoice(approval) === 'defer')
+        return deferred(input);
+    if (answerChoice(approval) !== 'approve')
+        return approval;
+    return output(await service.workItemApplyWorkflowSetup({
+        ...proposal,
+        repoRoot: input.repoRoot,
+        externalTaskId: input.externalTaskId,
+        questionnaireId,
+        selectionQuestionnaireIds,
+    }));
+}
+function deferred(input) {
+    return output({
+        ok: true,
+        data: {
+            status: 'deferred',
+            applied: false,
+            ...(input.decisionAttempt === 10000
+                ? {}
+                : {
+                    reconsider: {
+                        tool: 'work_item.setup_workflow',
+                        arguments: { ...input, decisionAttempt: (input.decisionAttempt ?? 0) + 1 },
+                    },
+                }),
+            nextAction: input.decisionAttempt === 10000
+                ? 'This attempt remains deferred. Use a new requestKey only after reconsideration is explicitly authorized.'
+                : 'No workflow settings were changed. Identical retries retain this deferral. Reconsider only after the user or current delegated decision explicitly resumes it.',
+        },
+    });
+}
+function refusal(message, recovery) {
+    return output({
+        ok: false,
+        error: { kind: 'workflow_setup', message, recovery, retryable: false },
+    });
+}
+function output(result) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(result) }],
+        isError: !result.ok,
+    };
+}
+//# sourceMappingURL=workflow-tools.js.map

package/runtime/dist/src/mcp/worktree-tools.js

@@ -228,6 +228,23 @@ const baseSchema = z.discriminatedUnion('kind', [
     z.strictObject({ kind: z.literal('local'), ref: branch }),
 ]);
 export function registerWorktreeTools(server, service) {
+    server.registerTool('worktree.prepare_files', {
+        description: "Inspect the current managed task worktree's paged Git-ignored file candidates without reading private values. After inspecting tracked runtime/build references, submit necessary relative paths and the exact expectedInventory to prepare them through normal same-clone, generation, staging and no-overwrite protections. An empty list records that no additional ignored files are needed. This is local file preparation, not a request to publish secrets. Resolve runtimeReview.required before claiming the worktree is ready.",
+        inputSchema: z
+            .strictObject({
+            repoRoot: repo,
+            externalTaskId: z.string().min(1).max(160),
+            generation: z.string().uuid(),
+            paths: z.array(z.string().min(1).max(500)).max(100).optional(),
+            expectedInventory: z
+                .string()
+                .regex(/^[a-f0-9]{64}$/)
+                .optional(),
+            offset: z.number().int().min(0).optional(),
+            limit: z.number().int().min(1).max(100).optional(),
+        })
+            .refine((input) => input.paths === undefined || input.expectedInventory !== undefined, 'A file selection requires expectedInventory.'),
+    }, async (input) => output(await service.worktreePrepareFiles(input)));
     server.registerTool('project.git_preferences', {
         description: 'Read the project development/production/test branch preferences and which questions remain unanswered. Only canManage actors may change shared choices; other members may select a task-specific base.',
         inputSchema: z.strictObject({

package/runtime/dist/src/runtime/api-client.js

@@ -21,6 +21,7 @@ export const backendRecoveryOperationNames = [
     'project.member_add',
     'work_item.list',
     'work_item.statuses',
+    'work_item.workflow',
     'work_item.get',
     'session.bootstrap',
     'session.resume',
@@ -95,6 +96,7 @@ export class ApiClient {
         return sha256(this.options.baseUrl.replace(/\/+$/, ''));
     }
     async request(path, request = {}) {
+        request.signal?.throwIfAborted();
         const method = request.method ?? 'GET';
         const cacheKey = request.cacheKey ?? this.cacheKey(method, path, request.body);
         const cached = request.cacheKey ? await this.options.cache.get(cacheKey) : null;
@@ -118,6 +120,12 @@ export class ApiClient {
             }
             headers.Authorization = `Bearer ${accessToken}`;
         }
+        const requestSignal = request.networkTimeoutMs === undefined
+            ? request.signal
+            : AbortSignal.any([
+                AbortSignal.timeout(request.networkTimeoutMs),
+                ...(request.signal ? [request.signal] : []),
+            ]);
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), this.options.timeoutMs);
         let response;
@@ -126,7 +134,9 @@ export class ApiClient {
                 method,
                 headers,
                 ...(request.body === undefined ? {} : { body: JSON.stringify(request.body) }),
-                signal: controller.signal,
+                signal: requestSignal
+                    ? AbortSignal.any([controller.signal, requestSignal])
+                    : controller.signal,
             });
         }
         catch (error) {
@@ -151,7 +161,7 @@ export class ApiClient {
         }
         let envelope;
         try {
-            envelope = await this.parseEnvelope(response);
+            envelope = await this.parseEnvelope(response, request.maxResponseBytes);
         }
         catch (error) {
             if (request.allowStaleOnUnavailable &&
@@ -252,10 +262,11 @@ export class ApiClient {
             await this.options.credentials.set('refresh-token', envelope.data.refreshToken);
         }
     }
-    async parseEnvelope(response) {
+    async parseEnvelope(response, maxBytes) {
         let value;
         try {
-            value = await response.json();
+            value =
+                maxBytes === undefined ? await response.json() : await this.boundedJson(response, maxBytes);
         }
         catch {
             throw new ApiResponseError(`Backend returned a non-JSON response with status ${response.status}`, response.status, null, response.status >= 500, null, null);
@@ -265,6 +276,29 @@ export class ApiClient {
         }
         return value;
     }
+    async boundedJson(response, maxBytes) {
+        const reader = response.body?.getReader();
+        if (!reader)
+            throw new Error('Empty response');
+        const chunks = [];
+        let size = 0;
+        try {
+            while (true) {
+                const part = await reader.read();
+                if (part.done)
+                    break;
+                size += part.value.byteLength;
+                if (size > maxBytes)
+                    throw new Error('Response exceeds the byte limit');
+                chunks.push(part.value);
+            }
+            return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        }
+        finally {
+            await reader.cancel().catch(() => undefined);
+            reader.releaseLock();
+        }
+    }
     cacheKey(method, path, body) {
         return sha256(`${method}\n${path}\n${stableStringify(body ?? null)}`);
     }