engineering-memory 1.11.11 → 1.11.13

package/runtime/dist/src/runtime/bridge-service.js

@@ -13,6 +13,7 @@ import { startPhaseTimer } from './phase-timer.js';
 import { sha256, stableStringify } from '../utilities/hash.js';
 import { ApiResponseError, BackendUnavailableError, } from './api-client.js';
 import { assertSafeToPersist, normalizeRepositoryPaths } from './offline-outbox.js';
+import { restrictedValueKind } from './privacy-detector.js';
 import { principalFingerprint } from './principal-state.js';
 import { sameHolder, suggestedBranchNames, taskStartChoice } from './task-start.js';
 import { BridgeRecoveryError } from './recovery-error.js';
@@ -49,13 +50,21 @@ export class BridgeService {
     managesWorktrees() {
         return Boolean(this.dependencies.worktreePool);
     }
+    async language(told) {
+        const accessToken = await this.dependencies.credentials.get('access-token');
+        const principalHash = accessToken ? principalFingerprint(accessToken) : sha256('anonymous');
+        if (told)
+            await this.dependencies.languages.remember(principalHash, told);
+        return told ?? (await this.dependencies.languages.read(principalHash));
+    }
     async questionnaireAsk(input, previousDefinitions = [], owner) {
         const scope = await this.questionnaireScope(input.repoRoot, input.preparation);
         const { repoRoot: _repoRoot, preparation: _preparation, presentation: _presentation, ...definition } = input;
         const askingTask = owner || input.preparation
             ? null
             : await this.checkoutTask(scope.repoFingerprint, await this.dependencies.repositories.git.findRoot(input.repoRoot ?? process.cwd()));
-        return await this.dependencies.questionnaires.ask(scope, definition, previousDefinitions, owner ?? (askingTask ? { tool: 'questionnaire.ask', externalTaskId: askingTask } : undefined));
+        const record = await this.dependencies.questionnaires.ask(scope, definition, previousDefinitions, owner ?? (askingTask ? { tool: 'questionnaire.ask', externalTaskId: askingTask } : undefined));
+        return { ...record, language: record.language ?? (await this.language()) };
     }
     async checkoutTask(repoFingerprint, repoRoot) {
         const worktreeId = sha256(await canonicalPath(repoRoot));
@@ -71,7 +80,7 @@ export class BridgeService {
         const record = await this.dependencies.questionnaires.get(scope, input.questionnaireId);
         if (!record)
             throw refuse('No questionnaire exists for this account and repository binding.', 'session.entry');
-        return record;
+        return { ...record, language: record.language ?? (await this.language()) };
     }
     async questionnaireWithdraw(input) {
         const scope = await this.questionnaireScope(input.repoRoot, input.preparation);
@@ -1242,7 +1251,9 @@ export class BridgeService {
                     ? await this.dependencies.questionnaires.get(scope, input.questionnaireId)
                     : null;
                 const digest = sha256(stableStringify(input.choice));
-                if (question?.answer?.choice !== 'approve' || !question.message.includes(digest))
+                if (question?.answer?.choice !== 'approve' ||
+                    (question.binding?.choiceDigest !== digest &&
+                        !question.message.includes(digest)))
                     throw refuse('Approve the exact mode and profile through project.onboard before continuing.', 'session.entry');
                 return asJsonValue(await this.dependencies.onboarding.save(scope, input.choice));
             }
@@ -1609,14 +1620,45 @@ export class BridgeService {
         }
         return [...pending];
     }
-    ruleDeviationQuestions(input) {
+    async ruleDeviationQuestions(input) {
+        const files = reviewedFiles(input);
+        if (!files.some(({ rules }) => rules.some(isDeviation)))
+            return [];
         const language = input.language ?? 'en';
-        return reviewedFiles(input).flatMap(({ path, rules }) => rules.filter(isDeviation).map((rule) => ({
-            definition: ruleDeviationQuestion(input.taskId, path, rule, language),
-            previousDefinitions: ['en', 'tr']
-                .filter((other) => other !== language)
-                .map((other) => ruleDeviationQuestion(input.taskId, path, rule, other)),
-        })));
+        const other = language === 'tr' ? 'en' : 'tr';
+        const titles = await this.governingRuleTitles(input).catch(() => new Map());
+        return files.flatMap(({ path, rules }) => rules.filter(isDeviation).map((rule) => {
+            const title = titles.get(rule.resourceId);
+            return {
+                definition: ruleDeviationQuestion(input.taskId, path, rule, title, language),
+                previousDefinitions: [
+                    ruleDeviationQuestion(input.taskId, path, rule, title, other),
+                    earlierRuleDeviationQuestion(input.taskId, path, rule, 'en'),
+                    earlierRuleDeviationQuestion(input.taskId, path, rule, 'tr'),
+                ],
+            };
+        }));
+    }
+    async governingRuleTitles(input) {
+        const { repoFingerprint } = await this.dependencies.repositories.resolveIdentity(input.repoRoot ?? process.cwd());
+        const pointer = await this.dependencies.activeContexts.loadForTask(repoFingerprint, input.taskId);
+        const prepared = pointer
+            ? await this.dependencies.client.readCached(resumeCacheKey(pointer.sessionId, repoFingerprint, 0))
+            : null;
+        const groups = objectValue(prepared?.data)?.governingRules;
+        return new Map((Array.isArray(groups) ? groups : [])
+            .flatMap((group) => {
+            const rules = objectValue(group)?.rules;
+            return Array.isArray(rules) ? rules : [];
+        })
+            .flatMap((entry) => {
+            const rule = objectValue(entry);
+            return typeof rule?.resourceId === 'string' &&
+                typeof rule.title === 'string' &&
+                !restrictedValueKind(rule.title, 'message', true)
+                ? [[rule.resourceId, rule.title]]
+                : [];
+        }));
     }
     async taskSelfReview(input) {
         return await this.execute(async () => {
@@ -3380,6 +3422,7 @@ export class BridgeService {
     async sessionEntry(input = {}) {
         return await this.execute(async () => {
             const timer = startPhaseTimer('session.entry');
+            await this.language(input.language);
             const authentication = await this.dependencies.browserAuth.status();
             timer.mark('auth_status');
             let repository;
@@ -3501,21 +3544,30 @@ export class BridgeService {
         }
     }
     async actionableWorkItems(projectId) {
+        const path = `${endpoints.workItemList(projectId)}?limit=100`;
         try {
-            const response = await this.dependencies.client.request(`${endpoints.workItemList(projectId)}?limit=100`);
-            const items = objectValue(response.data)?.items;
-            if (!Array.isArray(items))
+            const chosen = await this.workItemPage(`${path}&actionable=true`).catch((error) => {
+                if (error instanceof ApiResponseError && error.httpStatus === 400)
+                    return null;
+                throw error;
+            });
+            if (chosen && chosen.length > 0)
+                return chosen;
+            const every = await this.workItemPage(path);
+            if (chosen && every.some((entry) => objectValue(objectValue(entry)?.projectStatus) !== null))
                 return [];
             const actionable = new Set(['backlog', 'ready', 'in_progress', 'in_review']);
-            return items.filter((entry) => {
-                const item = objectValue(entry);
-                return item ? actionable.has(String(item.status)) : false;
-            });
+            return every.filter((entry) => actionable.has(String(objectValue(entry)?.status)));
         }
         catch {
             return [];
         }
     }
+    async workItemPage(path) {
+        const response = await this.dependencies.client.request(path);
+        const items = objectValue(response.data)?.items;
+        return Array.isArray(items) ? items : [];
+    }
     async clientUpdate(authenticated) {
         const installed = this.dependencies.clientVersion;
         if (!authenticated) {
@@ -4502,8 +4554,64 @@ export function ruleDeviationQuestionnaireId(taskId, path, rule) {
     return ('rule-deviation-' +
         sha256(stableStringify({ taskId, path, resourceKey: rule.resourceKey, issue: rule.issue })));
 }
-function ruleDeviationQuestion(taskId, path, rule, language) {
+function ruleDeviationQuestion(taskId, path, rule, title, language) {
     const copy = ruleDeviationCopy[language];
+    const named = rule.resourceKey && !/^[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(rule.resourceKey)
+        ? rule.resourceKey
+        : undefined;
+    return {
+        questionnaireId: ruleDeviationQuestionnaireId(taskId, path, rule),
+        message: [
+            copy.ask(path),
+            `${copy.rule}: ${title ?? named ?? copy.unnamed}`,
+            `${copy.deviation}: ${rule.issue ?? ''}`,
+        ].join('\n'),
+        context: copy.context,
+        example: copy.example,
+        language,
+        options: [
+            { id: 'approve', label: copy.approve[0], description: copy.approve[1] },
+            { id: 'change', label: copy.change[0], description: copy.change[1] },
+        ],
+        binding: { taskId, path, resourceId: rule.resourceId },
+    };
+}
+const ruleDeviationCopy = {
+    en: {
+        ask: (path) => `${path} breaks a rule of this project. Keep the code as it is?`,
+        rule: 'Rule',
+        deviation: 'Deviation',
+        unnamed: 'an engineering rule whose name is not recorded',
+        context: "A rule conflict is yours to decide, not the agent's. Keeping the code records a deviation on this file against that rule: it travels with the self review, stays in the project memory and is what a later task reads before it touches this file.",
+        example: 'The next task that opens this file sees the rule and this recorded deviation together, instead of reading the code as if it followed the rule.',
+        approve: [
+            'Keep the code and record the deviation',
+            'The deviation is recorded for this file and the self review continues.',
+        ],
+        change: [
+            'Change the code to follow the rule',
+            'Nothing is recorded. The self review stops until the code follows the rule and is reviewed again.',
+        ],
+    },
+    tr: {
+        ask: (path) => `${path} dosyası bu projenin bir kuralına uymuyor. Kod olduğu gibi kalsın mı?`,
+        rule: 'Kural',
+        deviation: 'Sapma',
+        unnamed: 'adı kayıtlı olmayan bir mühendislik kuralı',
+        context: 'Kural çatışmasında kararı kodu yazan değil sen verirsin. Kodu olduğu gibi bırakırsan bu dosya için o kurala ait bir sapma kaydedilir: sapma incelemeyle birlikte gider, proje hafızasında kalır ve bu dosyaya sonradan dokunan görev önce onu okur.',
+        example: 'Bu dosyayı sonra açan görev, kuralı ve kaydedilen bu sapmayı birlikte görür; kodu kurala uyuyormuş gibi okumaz.',
+        approve: [
+            'Kodu olduğu gibi bırak ve sapmayı kaydet',
+            'Sapma bu dosya için kaydedilir ve inceleme devam eder.',
+        ],
+        change: [
+            'Kodu kurala uyacak şekilde değiştir',
+            'Hiçbir şey kaydedilmez. Kod kurala uyup yeniden incelenene kadar inceleme durur.',
+        ],
+    },
+};
+function earlierRuleDeviationQuestion(taskId, path, rule, language) {
+    const copy = earlierRuleDeviationCopy[language];
     return {
         questionnaireId: ruleDeviationQuestionnaireId(taskId, path, rule),
         message: copy.message(path, rule.resourceKey ?? rule.resourceId, rule.issue ?? ''),
@@ -4514,7 +4622,7 @@ function ruleDeviationQuestion(taskId, path, rule, language) {
         ],
     };
 }
-const ruleDeviationCopy = {
+const earlierRuleDeviationCopy = {
     en: {
         message: (path, resourceKey, issue) => `${path} does not follow ${resourceKey}: ${issue}`,
         approve: 'Keep the code as written and record the deviation',

package/runtime/dist/src/runtime/create-bridge-service.js

@@ -14,6 +14,7 @@ import { OfflineOutbox } from './offline-outbox.js';
 import { ActiveContextStore } from './active-context-store.js';
 import { RepositoryDecisionStore } from './repository-decision-store.js';
 import { ShadowNoticeStore } from './shadow-notice-store.js';
+import { LanguageStore } from './language-store.js';
 import { UpdateChoiceStore } from './update-choice-store.js';
 import { PrincipalStateGuard } from './principal-state.js';
 import { OnboardingStore } from './onboarding-store.js';
@@ -73,6 +74,7 @@ export function createBridgeService(options = {}) {
         repositoryDecisions,
         updateChoices,
         shadowNotices,
+        languages: new LanguageStore(stateRoot),
         questionnaires: new QuestionnaireStore(stateRoot),
         onboarding: new OnboardingStore(stateRoot),
         clientVersion: options.clientVersion === undefined ? config.clientVersion : options.clientVersion,

package/runtime/dist/src/runtime/language-store.js

@@ -0,0 +1,25 @@
+import { join } from 'node:path';
+import { readJson, writeJson } from '../utilities/files.js';
+export class LanguageStore {
+    path;
+    root;
+    constructor(stateRoot) {
+        this.root = join(stateRoot, 'client');
+        this.path = join(this.root, 'language.json');
+    }
+    async read(principalHash) {
+        const remembered = await readJson(this.path, this.root);
+        return remembered?.principals[principalHash] ?? remembered?.machine;
+    }
+    async remember(principalHash, language) {
+        const remembered = await readJson(this.path, this.root);
+        if (remembered?.machine === language && remembered.principals[principalHash] === language)
+            return;
+        await writeJson(this.path, {
+            schemaVersion: 1,
+            machine: language,
+            principals: { ...remembered?.principals, [principalHash]: language },
+        }, this.root);
+    }
+}
+//# sourceMappingURL=language-store.js.map

package/runtime/dist/src/runtime/offline-outbox.js

@@ -151,10 +151,10 @@ export class OfflineOutbox {
         }
     }
 }
-export function assertSafeToPersist(value, key = '', path = key) {
+export function assertSafeToPersist(value, key = '', path = key, questionText = false) {
     if (typeof value === 'string' || typeof value === 'number') {
         const detector = typeof value === 'string'
-            ? restrictedValueKind(value, key)
+            ? restrictedValueKind(value, key, questionText)
             : restrictedNumberKind(value, key);
         if (detector) {
             throw new Error(`PII or credentials cannot be persisted: ${path || '(value)'} (${detector})`);
@@ -162,7 +162,7 @@ export function assertSafeToPersist(value, key = '', path = key) {
         return;
     }
     if (Array.isArray(value)) {
-        value.forEach((item, index) => assertSafeToPersist(item, key, `${path}[${index}]`));
+        value.forEach((item, index) => assertSafeToPersist(item, key, `${path}[${index}]`, questionText));
         return;
     }
     if (value !== null && typeof value === 'object') {
@@ -171,7 +171,7 @@ export function assertSafeToPersist(value, key = '', path = key) {
             if (field) {
                 throw new Error(`Sensitive field cannot be persisted: ${childPath(path, childKey)} (${field})`);
             }
-            assertSafeToPersist(item, childKey, childPath(path, childKey));
+            assertSafeToPersist(item, childKey, childPath(path, childKey), questionText);
         });
     }
 }

package/runtime/dist/src/runtime/privacy-detector.js

@@ -13,6 +13,14 @@ const repositoryPathFields = new Set([
     'pathChanges',
     'templatePath',
 ]);
+const questionTextFields = new Set([
+    'message',
+    'context',
+    'example',
+    'label',
+    'description',
+    'title',
+]);
 const topLevelDomains = new Set([
     'com',
     'net',
@@ -151,8 +159,9 @@ export function restrictedNumberKind(value, key) {
         ? 'phone number'
         : null;
 }
-export function restrictedValueKind(value, key) {
+export function restrictedValueKind(value, key, questionText = false) {
     const repositoryPath = repositoryPathFields.has(key);
+    const prose = questionText && questionTextFields.has(key);
     if (hasEmailAddress(value, repositoryPath))
         return 'email address';
     if (privateKeyPattern.test(value))
@@ -167,9 +176,9 @@ export function restrictedValueKind(value, key) {
         return 'personal home directory';
     if (hasBearerCredential(value))
         return 'bearer credential';
-    if (hasPhoneNumber(value))
+    if (hasPhoneNumber(value, prose))
         return 'phone number';
-    if (!repositoryPath && hasIpv4Address(value))
+    if (!repositoryPath && !prose && hasIpv4Address(value))
         return 'network address';
     if (hasSecretAssignment(value))
         return 'assigned secret';
@@ -234,11 +243,11 @@ function hasIpv4Address(value) {
     }
     return false;
 }
-function hasPhoneNumber(value) {
+function hasPhoneNumber(value, prose = false) {
     const trimmed = value.trim();
     if (uuidPattern.test(trimmed))
         return false;
-    if (/^\d{10,11}$/.test(trimmed))
+    if (!prose && /^\d{10,11}$/.test(trimmed))
         return true;
     if (/(?:^|[^A-Z0-9])0?5\d{2}[\s.-]?\d{3}[\s.-]?\d{2}[\s.-]?\d{2}(?![A-Z0-9])/i.test(value)) {
         return true;

package/runtime/dist/src/runtime/questionnaire-store.js

@@ -7,12 +7,14 @@ import { sha256, stableStringify } from '../utilities/hash.js';
 import { assertSafeToPersist } from './offline-outbox.js';
 const identifier = z.string().regex(/^[A-Za-z0-9_-]{1,100}$/);
 const questionId = z.string().regex(/^[a-z][a-z0-9_]{0,39}$/);
+export const languageTag = z.string().regex(/^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/);
 const optionSchema = z.strictObject({
     id: z
         .string()
         .regex(/^[A-Za-z0-9_-]{1,80}$/)
-        .refine((value) => value !== '__other__'),
+        .refine((value) => value !== '__other__' && value !== '__explain__'),
     label: z.string().trim().min(1).max(240),
+    description: z.string().trim().min(1).max(400).optional(),
 });
 const textFieldSchema = z.strictObject({
     title: z.string().trim().min(1).max(120),
@@ -27,6 +29,8 @@ const subQuestionSchema = z
     .strictObject({
     id: questionId,
     message: z.string().trim().min(1).max(600),
+    context: z.string().trim().min(1).max(1200).optional(),
+    example: z.string().trim().min(1).max(600).optional(),
     options: z
         .array(optionSchema)
         .min(2)
@@ -73,10 +77,23 @@ function attachDefinitionChecks(schema) {
 const questionnaireDefinitionShape = z.strictObject({
     questionnaireId: identifier,
     message: z.string().trim().min(1).max(2000),
-    language: z
-        .enum(['tr', 'en'])
+    context: z
+        .string()
+        .trim()
+        .min(1)
+        .max(1200)
+        .optional()
+        .describe('Why this is being asked, in the language of the conversation.'),
+    example: z
+        .string()
+        .trim()
+        .min(1)
+        .max(600)
+        .optional()
+        .describe('One concrete example of what the decision changes.'),
+    language: languageTag
         .optional()
-        .describe('Language of the current conversation: tr for Turkish, en for English. Translate the message and option labels into that language too.'),
+        .describe('Language the user is writing in, as a BCP-47 tag such as tr, en or pt-BR. Write the message, context, example, option labels and descriptions in that language too.'),
     options: z
         .array(optionSchema)
         .min(2)
@@ -234,7 +251,7 @@ export class QuestionnaireStore {
         scopeSchema.parse(scope);
         if (owner)
             ownerSchema.parse(owner);
-        assertSafeToPersist(definition);
+        assertSafeToPersist(definition, '', '', true);
         const contentHash = sha256(stableStringify(definition));
         const question = {
             ...definition,
@@ -261,6 +278,8 @@ export class QuestionnaireStore {
         const definition = boundDefinitionSchema.parse({
             questionnaireId: question.questionnaireId,
             message: question.message,
+            context: question.context,
+            example: question.example,
             language: question.language,
             options: question.options,
             allowFreeText: question.allowFreeText,
@@ -274,7 +293,7 @@ export class QuestionnaireStore {
             question.contentHash !== sha256(stableStringify(definition))) {
             throw new Error('Questionnaire scope or content does not match its durable record.');
         }
-        assertSafeToPersist(question);
+        assertSafeToPersist(question, '', '', true);
         const rawAnswer = await readJson(this.pathFor(scope, questionnaireId, 'answer.json'), this.root);
         if (!rawAnswer)
             return { ...question, status: 'pending' };
@@ -427,7 +446,7 @@ export class QuestionnaireStore {
         return join(this.scopeRoot(scope), sha256(questionnaireId), filename);
     }
     async publish(path, value) {
-        assertSafeToPersist(value);
+        assertSafeToPersist(value, '', '', true);
         const temporaryPath = `${path}.${randomUUID()}.tmp`;
         await writeJson(temporaryPath, value, this.root);
         try {