engineering-memory 1.11.9 → 1.11.11

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

@@ -6,7 +6,71 @@ import { assertManagedPath, ensureManagedDirectory, isNodeError, readJson, remov
 import { sha256, stableStringify } from '../utilities/hash.js';
 import { assertSafeToPersist } from './offline-outbox.js';
 const identifier = z.string().regex(/^[A-Za-z0-9_-]{1,100}$/);
-export const questionnaireDefinitionSchema = z.strictObject({
+const questionId = z.string().regex(/^[a-z][a-z0-9_]{0,39}$/);
+const optionSchema = z.strictObject({
+    id: z
+        .string()
+        .regex(/^[A-Za-z0-9_-]{1,80}$/)
+        .refine((value) => value !== '__other__'),
+    label: z.string().trim().min(1).max(240),
+});
+const textFieldSchema = z.strictObject({
+    title: z.string().trim().min(1).max(120),
+    maxLength: z.number().int().min(1).max(2000),
+    requiredForChoice: z
+        .string()
+        .regex(/^[A-Za-z0-9_-]{1,80}$/)
+        .optional(),
+    valueType: z.enum(['text', 'uuid_list']).optional(),
+});
+const subQuestionSchema = z
+    .strictObject({
+    id: questionId,
+    message: z.string().trim().min(1).max(600),
+    options: z
+        .array(optionSchema)
+        .min(2)
+        .max(4)
+        .refine((values) => new Set(values.map((value) => value.id)).size === values.length),
+    otherAsText: z.boolean().default(false),
+    textField: textFieldSchema.optional(),
+})
+    .refine((value) => !value.otherAsText ||
+    (value.options.some((option) => option.id === 'other') &&
+        value.textField?.requiredForChoice === 'other'), 'otherAsText requires an "other" option with a textField required for that choice.');
+const ownerSchema = z.strictObject({
+    tool: z.string().min(1).max(80),
+    externalTaskId: z.string().min(1).max(160).optional(),
+    decisionAttempt: z.number().int().min(1).max(10000).optional(),
+    retryArguments: z.record(z.string(), z.unknown()).optional(),
+});
+function definitionIssues(value) {
+    const issues = [];
+    const hasOptions = value.options !== undefined;
+    const hasQuestions = value.questions !== undefined;
+    if (hasOptions === hasQuestions)
+        issues.push('Exactly one of options or questions must be set.');
+    if (hasQuestions && (value.allowFreeText || value.textField))
+        issues.push('allowFreeText and textField apply only to a single-question definition.');
+    if (value.terminalChoices) {
+        if (!hasQuestions)
+            issues.push('terminalChoices requires questions.');
+        else {
+            const ids = new Set((value.questions ?? []).map((question) => question.id));
+            for (const terminal of value.terminalChoices)
+                if (!ids.has(terminal.questionId))
+                    issues.push(`terminalChoices references unknown question "${terminal.questionId}".`);
+        }
+    }
+    return issues;
+}
+function attachDefinitionChecks(schema) {
+    return schema.superRefine((value, ctx) => {
+        for (const message of definitionIssues(value))
+            ctx.addIssue({ code: 'custom', message });
+    });
+}
+const questionnaireDefinitionShape = z.strictObject({
     questionnaireId: identifier,
     message: z.string().trim().min(1).max(2000),
     language: z
@@ -14,51 +78,60 @@ export const questionnaireDefinitionSchema = z.strictObject({
         .optional()
         .describe('Language of the current conversation: tr for Turkish, en for English. Translate the message and option labels into that language too.'),
     options: z
-        .array(z.strictObject({
-        id: z
-            .string()
-            .regex(/^[A-Za-z0-9_-]{1,80}$/)
-            .refine((value) => value !== '__other__'),
-        label: z.string().trim().min(1).max(240),
-    }))
+        .array(optionSchema)
         .min(2)
         .max(12)
-        .refine((values) => new Set(values.map((value) => value.id)).size === values.length),
+        .refine((values) => new Set(values.map((value) => value.id)).size === values.length)
+        .optional(),
     allowFreeText: z.boolean().default(false),
-    textField: z
-        .strictObject({
-        title: z.string().trim().min(1).max(120),
-        maxLength: z.number().int().min(1).max(2000),
-        requiredForChoice: z
-            .string()
-            .regex(/^[A-Za-z0-9_-]{1,80}$/)
-            .optional(),
-        valueType: z.enum(['text', 'uuid_list']).optional(),
-    })
+    textField: textFieldSchema.optional(),
+    questions: z
+        .array(subQuestionSchema)
+        .min(1)
+        .max(8)
+        .refine((values) => new Set(values.map((value) => value.id)).size === values.length)
+        .optional(),
+    terminalChoices: z
+        .array(z.strictObject({ questionId, choice: z.string().regex(/^[A-Za-z0-9_-]{1,80}$/) }))
+        .max(8)
         .optional(),
 });
+export const questionnaireDefinitionSchema = attachDefinitionChecks(questionnaireDefinitionShape);
+const boundDefinitionShape = questionnaireDefinitionShape.extend({
+    binding: z.record(z.string(), z.json()).optional(),
+});
+const boundDefinitionSchema = attachDefinitionChecks(boundDefinitionShape);
 const scopeSchema = z.strictObject({
     principalHash: z.string().regex(/^[0-9a-f]{64}$/),
     repoFingerprint: z.string().regex(/^[0-9a-f]{64}$/),
     projectId: z.string().uuid().nullable(),
 });
-const storedQuestionSchema = questionnaireDefinitionSchema.extend({
+const storedQuestionSchema = attachDefinitionChecks(boundDefinitionShape.extend({
     schemaVersion: z.literal(1),
     scope: scopeSchema,
     contentHash: z.string().regex(/^[0-9a-f]{64}$/),
     requestKey: z.string().regex(/^questionnaire_[0-9a-f]{64}$/),
     createdAt: z.string().datetime(),
-});
-export const hostAnswerSchema = z.strictObject({
+    owner: ownerSchema.optional(),
+}));
+const singleAnswerShape = z.strictObject({ choice: z.string(), text: z.string().optional() });
+export const hostAnswerSchema = z
+    .strictObject({
     questionnaireId: identifier,
     requestKey: z.string().regex(/^questionnaire_[0-9a-f]{64}$/),
     contentHash: z.string().regex(/^[0-9a-f]{64}$/),
     hostTool: z.enum(['AskUserQuestion', 'request_user_input']),
-    answer: z.strictObject({
+    answer: z
+        .strictObject({ choice: z.string().min(1).max(80), text: z.string().max(2000).optional() })
+        .optional(),
+    answers: z
+        .record(questionId, z.strictObject({
         choice: z.string().min(1).max(80),
         text: z.string().max(2000).optional(),
-    }),
-});
+    }))
+        .optional(),
+})
+    .refine((value) => Boolean(value.answer) !== Boolean(value.answers), 'Exactly one of answer or answers must be set.');
 const answerSourceSchema = z.strictObject({
     kind: z.literal('host_native_relay'),
     hostTool: z.enum(['AskUserQuestion', 'request_user_input']),
@@ -69,9 +142,10 @@ const storedAnswerSchema = z.strictObject({
     answerAvailable: z.boolean(),
     withdrawn: z.literal(true).optional(),
     answerSource: answerSourceSchema.optional(),
-    answer: z.strictObject({ choice: z.string(), text: z.string().optional() }).optional(),
+    answer: singleAnswerShape.optional(),
+    answers: z.record(questionId, singleAnswerShape).optional(),
 });
-export function questionnaireAnswerSchema(record) {
+function singleQuestionAnswerSchema(record) {
     const textSchema = record.textField
         ? record.textField.valueType === 'uuid_list'
             ? z
@@ -111,20 +185,55 @@ export function questionnaireAnswerSchema(record) {
         return answer.text === undefined;
     });
 }
+function multiQuestionAnswerSchema(record) {
+    const terminal = record.terminalChoices ?? [];
+    const shape = {};
+    for (const sub of record.questions) {
+        const optionIds = sub.options.map((option) => option.id);
+        const textSchema = sub.textField
+            ? z.string().trim().min(1).max(sub.textField.maxLength).optional()
+            : z.never().optional();
+        shape[sub.id] = z
+            .strictObject({
+            choice: z.enum(optionIds),
+            text: z.preprocess((value) => (typeof value === 'string' && value.trim() === '' ? undefined : value), textSchema),
+        })
+            .refine((answer) => {
+            if (sub.textField?.requiredForChoice === answer.choice)
+                return typeof answer.text === 'string';
+            return answer.text === undefined;
+        })
+            .optional();
+    }
+    return z.strictObject(shape).refine((value) => {
+        const answers = value;
+        const terminalHit = terminal.some((choice) => answers[choice.questionId]?.choice === choice.choice);
+        if (terminalHit)
+            return true;
+        return record.questions.every((sub) => answers[sub.id] !== undefined);
+    }, 'All questions must be answered unless a terminal choice was picked.');
+}
+export function questionnaireAnswerSchema(record) {
+    return record.questions
+        ? multiQuestionAnswerSchema(record)
+        : singleQuestionAnswerSchema(record);
+}
 export class QuestionnaireStore {
     root;
     constructor(stateRoot) {
         this.root = join(stateRoot, 'questionnaires');
     }
-    async ask(scope, input, previousDefinitions = []) {
-        const definition = questionnaireDefinitionSchema.parse(input);
+    async ask(scope, input, previousDefinitions = [], owner) {
+        const definition = boundDefinitionSchema.parse(input);
         const previousHashes = previousDefinitions.map((previous) => {
-            const parsed = questionnaireDefinitionSchema.parse(previous);
+            const parsed = boundDefinitionSchema.parse(previous);
             if (parsed.questionnaireId !== definition.questionnaireId)
                 throw new Error('Previous questionnaire content must belong to the same decision.');
             return sha256(stableStringify(parsed));
         });
         scopeSchema.parse(scope);
+        if (owner)
+            ownerSchema.parse(owner);
         assertSafeToPersist(definition);
         const contentHash = sha256(stableStringify(definition));
         const question = {
@@ -134,6 +243,7 @@ export class QuestionnaireStore {
             contentHash,
             requestKey: `questionnaire_${sha256(`${stableStringify(scope)}\n${contentHash}\n${randomUUID()}`)}`,
             createdAt: new Date().toISOString(),
+            ...(owner ? { owner } : {}),
         };
         await this.publish(this.pathFor(scope, definition.questionnaireId, 'pending.json'), question);
         const record = await this.get(scope, definition.questionnaireId);
@@ -148,13 +258,16 @@ export class QuestionnaireStore {
         if (!raw)
             return null;
         const question = storedQuestionSchema.parse(raw);
-        const definition = questionnaireDefinitionSchema.parse({
+        const definition = boundDefinitionSchema.parse({
             questionnaireId: question.questionnaireId,
             message: question.message,
             language: question.language,
             options: question.options,
             allowFreeText: question.allowFreeText,
             textField: question.textField,
+            questions: question.questions,
+            terminalChoices: question.terminalChoices,
+            binding: question.binding,
         });
         if (stableStringify(question.scope) !== stableStringify(scope) ||
             question.questionnaireId !== questionnaireId ||
@@ -167,11 +280,36 @@ export class QuestionnaireStore {
             return { ...question, status: 'pending' };
         const answer = storedAnswerSchema.parse(rawAnswer);
         if (answer.withdrawn) {
-            if (answer.requestKey !== question.requestKey || answer.answerAvailable || answer.answer)
+            if (answer.requestKey !== question.requestKey ||
+                answer.answerAvailable ||
+                answer.answer ||
+                answer.answers)
                 throw new Error('Invalid questionnaire withdrawal receipt.');
             return { ...question, ...answer, status: 'withdrawn' };
         }
+        if (question.questions) {
+            if (answer.requestKey !== question.requestKey ||
+                !answer.answerAvailable ||
+                !answer.answers ||
+                answer.answer !== undefined)
+                throw new Error('Questionnaire answer does not match its durable question.');
+            for (const [id, value] of Object.entries(answer.answers)) {
+                const sub = question.questions.find((item) => item.id === id);
+                if (!sub || !sub.options.some((option) => option.id === value.choice))
+                    throw new Error('Questionnaire answer does not match its durable question.');
+                if (value.text !== undefined && !sub.textField)
+                    throw new Error('Questionnaire text answer does not match its durable question.');
+                if (sub.textField?.requiredForChoice === value.choice && typeof value.text !== 'string')
+                    throw new Error('Questionnaire text answer is required for this choice.');
+            }
+            const terminalHit = (question.terminalChoices ?? []).some((choice) => answer.answers[choice.questionId]?.choice === choice.choice);
+            if (!terminalHit && !question.questions.every((sub) => answer.answers[sub.id] !== undefined))
+                throw new Error('Questionnaire answer is missing a required question.');
+            assertSafeToPersist(answer);
+            return { ...question, ...answer, status: 'answered' };
+        }
         if (answer.requestKey !== question.requestKey ||
+            answer.answers !== undefined ||
             (answer.answerAvailable
                 ? !answer.answer || !question.options.some((option) => option.id === answer.answer.choice)
                 : !question.allowFreeText || answer.answer !== undefined)) {
@@ -187,6 +325,12 @@ export class QuestionnaireStore {
         return { ...question, ...answer, status: 'answered' };
     }
     async pending(scope) {
+        return (await this.scan(scope)).filter((record) => record.status === 'pending');
+    }
+    async list(scope) {
+        return this.scan(scope);
+    }
+    async scan(scope) {
         const directory = this.scopeRoot(scope);
         await ensureManagedDirectory(this.root, directory);
         const entries = await readdir(directory, { withFileTypes: true });
@@ -204,7 +348,7 @@ export class QuestionnaireStore {
             if (sha256(question.questionnaireId) !== entry.name)
                 throw new Error('Questionnaire directory does not match its id.');
             const record = await this.get(scope, question.questionnaireId);
-            if (record?.status === 'pending')
+            if (record)
                 records.push(record);
         }
         return records.sort((left, right) => left.createdAt.localeCompare(right.createdAt));
@@ -217,31 +361,48 @@ export class QuestionnaireStore {
             throw new Error('Questionnaire response is stale or belongs to a different scope.');
         if (record.status === 'withdrawn')
             throw new Error('Questionnaire was explicitly withdrawn. Start a new decision if the user resumes the work.');
-        const answer = questionnaireAnswerSchema(record).parse(input);
-        assertSafeToPersist(answer);
+        const parsed = questionnaireAnswerSchema(record).parse(input);
+        assertSafeToPersist(parsed);
         if (record.status === 'answered') {
-            if (record.answer && stableStringify(record.answer) !== stableStringify(answer))
+            const stored = record.questions ? record.answers : record.answer;
+            if (stored !== undefined && stableStringify(stored) !== stableStringify(parsed))
                 throw new Error('Questionnaire was already answered differently.');
-            return { record, answer: record.answer, replayed: true };
+            return { record, answer: stored, replayed: true };
         }
-        const receipt = {
-            requestKey,
-            ...(answerSource ? { answerSource } : {}),
-            answeredAt: new Date().toISOString(),
-            answerAvailable: answer.choice !== '__other__',
-            ...(answer.choice !== '__other__'
-                ? { answer: { choice: answer.choice, ...(answer.text ? { text: answer.text } : {}) } }
-                : {}),
-        };
+        const receipt = record.questions
+            ? {
+                requestKey,
+                ...(answerSource ? { answerSource } : {}),
+                answeredAt: new Date().toISOString(),
+                answerAvailable: true,
+                answers: parsed,
+            }
+            : (() => {
+                const answer = parsed;
+                return {
+                    requestKey,
+                    ...(answerSource ? { answerSource } : {}),
+                    answeredAt: new Date().toISOString(),
+                    answerAvailable: answer.choice !== '__other__',
+                    ...(answer.choice !== '__other__'
+                        ? { answer: { choice: answer.choice, ...(answer.text ? { text: answer.text } : {}) } }
+                        : {}),
+                };
+            })();
         const published = await this.publish(this.pathFor(scope, questionnaireId, 'answer.json'), receipt);
         const resolved = (await this.get(scope, questionnaireId));
         if (resolved.status === 'withdrawn')
             throw new Error('Questionnaire was explicitly withdrawn before this response.');
+        const resolvedStored = record.questions ? resolved.answers : resolved.answer;
         if (!published &&
-            resolved.answer &&
-            stableStringify(resolved.answer) !== stableStringify(answer))
+            resolvedStored !== undefined &&
+            stableStringify(resolvedStored) !== stableStringify(parsed))
             throw new Error('Questionnaire was already answered differently.');
-        return { record: resolved, answer: published ? answer : resolved.answer, replayed: !published };
+        return {
+            record: resolved,
+            answer: published ? parsed : resolvedStored,
+            replayed: !published,
+        };
     }
     async withdraw(scope, questionnaireId) {
         const record = await this.get(scope, questionnaireId);

package/runtime/dist/src/runtime/recovery-error.js

@@ -1,8 +1,10 @@
 export class BridgeRecoveryError extends Error {
     recovery;
-    constructor(message, recovery) {
+    details;
+    constructor(message, recovery, details) {
         super(`${message} Recovery: call ${recovery}.`);
         this.recovery = recovery;
+        this.details = details;
         this.name = 'BridgeRecoveryError';
     }
 }

package/runtime/dist/src/runtime/runtime-entry.js

@@ -1,9 +1,17 @@
 import { registerAllTools } from '../mcp/server.js';
+import { toolAnnotations } from '../mcp/tool-annotations.js';
 import { recordingHost } from '../mcp/tool-host.js';
 import { createBridgeService } from './create-bridge-service.js';
 export function collectTools(service, server) {
     const recording = recordingHost(server);
     registerAllTools(recording.host, service);
+    const described = toolAnnotations;
+    for (const spec of recording.tools) {
+        const annotations = described[spec.name];
+        if (!annotations)
+            throw new Error(`Tool ${spec.name} has no entry in tool-annotations.ts; describe it there.`);
+        spec.config = { ...spec.config, annotations: { ...annotations, ...spec.config.annotations } };
+    }
     return recording.tools;
 }
 export function createRuntime(options) {

package/runtime/dist/src/runtime/runtime-host.js

@@ -171,9 +171,7 @@ export class RuntimeHost {
                     ...(spec.config.outputSchema !== undefined
                         ? { outputSchema: spec.config.outputSchema }
                         : {}),
-                    ...(spec.config.annotations !== undefined
-                        ? { annotations: spec.config.annotations }
-                        : {}),
+                    annotations: spec.config.annotations ?? {},
                 });
                 existing.signature = signature;
             }

package/runtime/dist/src/runtime/task-branch-store.js

@@ -89,10 +89,26 @@ export class TaskBranchStore {
             throw new BridgeRecoveryError('The task has finished but its worktree reservation could not be released. Resume the task to retry cleanup.', 'session.resume');
         }
     }
+    async detach(expected, oid) {
+        const current = await this.read();
+        const changed = () => new BridgeRecoveryError(`The reservation of this folder changed after the question about ${expected.externalTaskId} was asked. Call task.branch again; its question shows which task holds the folder now.`, 'task.branch');
+        if (!current ||
+            current.oid !== oid ||
+            current.decision.projectId !== expected.projectId ||
+            current.decision.externalTaskId !== expected.externalTaskId ||
+            current.decision.taskId !== expected.taskId)
+            throw changed();
+        const result = await this.runner.run('git', ['update-ref', '--no-deref', '-d', decisionRef, oid], { cwd: this.repoRoot });
+        if (result.exitCode !== 0) {
+            if ((await this.read())?.oid !== oid)
+                throw changed();
+            throw new BridgeRecoveryError('Git could not move the task out of this folder. Retry task.branch; nothing was changed.', 'task.branch');
+        }
+    }
     assertSame(current, requested) {
         if (current.projectId !== requested.projectId ||
             current.externalTaskId !== requested.externalTaskId) {
-            throw new BridgeRecoveryError(`This worktree belongs to task ${current.externalTaskId}. Resume that task, or call task.branch with a new task branch name to allocate a separate worktree.`, 'task.branch');
+            throw new BridgeRecoveryError(`This folder is held by task ${current.externalTaskId}. Continue that task, or call task.branch for the new task: its question offers a separate worktree, or a new branch in this folder after asking whether ${current.externalTaskId} should move out.`, 'task.branch');
         }
         if (current.branch !== requested.branch) {
             throw new BridgeRecoveryError(`This task selected ${current.branch ?? 'detached HEAD'}. Return to that branch before continuing.`, 'task.branch');