@1aboveio/skills 0.10.0

package/skills/engineering/harness-runtime/index.mjs

@@ -0,0 +1,767 @@
+const HARNESSES = new Set(['pi', 'codex', 'claude-code']);
+const COMPLETENESS = new Set(['partial', 'full']);
+const RUNTIME_MODEL_SOURCES = new Set(['current-turn', 'runtime-enumeration']);
+
+export const HARNESS_RUNTIME_ERROR_CODES = Object.freeze({
+  INVALID_CAPABILITIES: 'invalid-capabilities',
+  INVALID_QUESTION: 'invalid-question',
+  INVALID_ANSWERS: 'invalid-answers',
+  INVALID_MODEL_AVAILABILITY: 'invalid-model-availability',
+  CAPABILITY_UNAVAILABLE: 'capability-unavailable',
+  UNSUPPORTED_QUESTION: 'unsupported-question',
+  FALLBACK_FORBIDDEN: 'fallback-forbidden',
+});
+
+function deepFreeze(value) {
+  if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+    for (const child of Object.values(value)) deepFreeze(child);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+function clone(value) {
+  return structuredClone(value);
+}
+
+export class HarnessRuntimeError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = 'HarnessRuntimeError';
+    this.code = code;
+    this.details = deepFreeze(clone(details));
+  }
+}
+
+export class CapabilityUnavailableError extends HarnessRuntimeError {
+  constructor(capability, details = {}) {
+    super(
+      HARNESS_RUNTIME_ERROR_CODES.CAPABILITY_UNAVAILABLE,
+      `Required harness capability is unavailable: ${capability}`,
+      { ...details, capability },
+    );
+    this.name = 'CapabilityUnavailableError';
+    this.capability = capability;
+  }
+}
+
+export class UnsupportedQuestionError extends HarnessRuntimeError {
+  constructor(reason, details = {}) {
+    super(
+      HARNESS_RUNTIME_ERROR_CODES.UNSUPPORTED_QUESTION,
+      `Question cannot be represented by the selected native adapter: ${reason}`,
+      { ...details, reason },
+    );
+    this.name = 'UnsupportedQuestionError';
+    this.reason = reason;
+  }
+}
+
+export const QUESTION_ADAPTER_PRIORITY = Object.freeze([
+  'ask_user_question',
+  'request_user_input',
+  'AskUserQuestion',
+]);
+
+export const QUESTION_FALLBACK_POLICY = deepFreeze({
+  noNativeQuestionTool: {
+    freeText: 'concise-free-text-only',
+    multipleChoice: 'forbidden',
+  },
+  unsupportedMultiSelect: 'error',
+  secretInput: 'error',
+});
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function hasExactFields(value, required, optional = []) {
+  if (!isRecord(value)) return false;
+  const allowed = new Set([...required, ...optional]);
+  return required.every((field) => Object.hasOwn(value, field))
+    && Object.keys(value).every((field) => allowed.has(field));
+}
+
+function nonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function stringList(value, { allowEmpty = true } = {}) {
+  return Array.isArray(value)
+    && (allowEmpty || value.length > 0)
+    && value.every(nonEmptyString)
+    && new Set(value).size === value.length;
+}
+
+function invalid(code, label, details = {}) {
+  throw new HarnessRuntimeError(code, `Invalid harness runtime ${label}.`, details);
+}
+
+export function defineCurrentTurnCapabilities(value) {
+  if (!hasExactFields(value, ['nativeTools', 'spawnModelIds'])
+    || !stringList(value.nativeTools)
+    || !stringList(value.spawnModelIds)) {
+    invalid(HARNESS_RUNTIME_ERROR_CODES.INVALID_CAPABILITIES, 'current-turn capabilities');
+  }
+  return deepFreeze(clone(value));
+}
+
+function validOption(option) {
+  return hasExactFields(option, ['id', 'label'], ['description'])
+    && nonEmptyString(option.id)
+    && nonEmptyString(option.label)
+    && (option.description === undefined || nonEmptyString(option.description));
+}
+
+export function defineQuestionSpec(value) {
+  if (!hasExactFields(
+    value,
+    ['id', 'header', 'prompt'],
+    ['options', 'recommendationOrder', 'multiSelect', 'secret'],
+  ) || !nonEmptyString(value.id)
+    || !nonEmptyString(value.header)
+    || !nonEmptyString(value.prompt)) {
+    invalid(HARNESS_RUNTIME_ERROR_CODES.INVALID_QUESTION, 'question');
+  }
+
+  const options = value.options ?? [];
+  const optionIds = options.map((option) => option?.id);
+  const recommendationOrder = value.recommendationOrder ?? [];
+  if (!Array.isArray(options)
+    || !options.every(validOption)
+    || new Set(optionIds).size !== optionIds.length
+    || !stringList(recommendationOrder)
+    || recommendationOrder.some((id) => !optionIds.includes(id))
+    || (value.multiSelect !== undefined && typeof value.multiSelect !== 'boolean')
+    || (value.secret !== undefined && typeof value.secret !== 'boolean')) {
+    invalid(HARNESS_RUNTIME_ERROR_CODES.INVALID_QUESTION, 'question', { questionId: value.id });
+  }
+
+  return deepFreeze({
+    id: value.id,
+    header: value.header,
+    prompt: value.prompt,
+    options: clone(options),
+    recommendationOrder: clone(recommendationOrder),
+    multiSelect: value.multiSelect ?? false,
+    secret: value.secret ?? false,
+  });
+}
+
+function orderedQuestionOptions(question) {
+  const byId = new Map(question.options.map((option) => [option.id, option]));
+  return [
+    ...question.recommendationOrder.map((id) => byId.get(id)),
+    ...question.options.filter((option) => !question.recommendationOrder.includes(option.id)),
+  ];
+}
+
+function answerMappings(batch, optionLabel = (_question, option) => option.label) {
+  return batch.map((question) => ({
+    questionId: question.id,
+    prompt: question.prompt,
+    multiSelect: question.multiSelect,
+    options: orderedQuestionOptions(question).map((option) => ({
+      id: option.id,
+      label: optionLabel(question, option),
+    })),
+  }));
+}
+
+function validateNativeOptionLabels(question, adapter, optionLabel = (_question, option) => option.label) {
+  const nativeOptions = orderedQuestionOptions(question).map((option) => ({
+    id: option.id,
+    label: optionLabel(question, option),
+  }));
+  const labels = new Map();
+  for (const option of nativeOptions) {
+    const existingId = labels.get(option.label);
+    if (existingId !== undefined) {
+      invalid(HARNESS_RUNTIME_ERROR_CODES.INVALID_QUESTION, 'question', {
+        reason: 'native-option-label-collision',
+        adapter,
+        questionId: question.id,
+        label: option.label,
+        optionIds: [existingId, option.id],
+      });
+    }
+    labels.set(option.label, option.id);
+  }
+  return nativeOptions;
+}
+
+function claudeMultiAnswerMappings(options) {
+  const mappings = [];
+  for (let mask = 1; mask < (1 << options.length); mask += 1) {
+    const subset = options.filter((_, index) => mask & (1 << index));
+    for (const candidate of permutations(subset)) {
+      mappings.push({
+        answer: candidate.map((option) => option.label).join(', '),
+        optionIds: candidate.map((option) => option.id),
+      });
+    }
+  }
+  return mappings;
+}
+
+function validateClaudeMultiAnswerFormats(question, nativeOptions) {
+  if (!question.multiSelect) return;
+  const formats = new Map();
+  for (const mapping of claudeMultiAnswerMappings(nativeOptions)) {
+    const existing = formats.get(mapping.answer);
+    if (existing !== undefined
+      && JSON.stringify(existing) !== JSON.stringify(mapping.optionIds)) {
+      invalid(HARNESS_RUNTIME_ERROR_CODES.INVALID_QUESTION, 'question', {
+        reason: 'native-answer-format-collision',
+        adapter: 'claude-code',
+        questionId: question.id,
+        answer: mapping.answer,
+        optionIdSets: [existing, mapping.optionIds],
+      });
+    }
+    formats.set(mapping.answer, mapping.optionIds);
+  }
+}
+
+function validateQuestionBatch(values) {
+  if (!Array.isArray(values) || values.length === 0) {
+    invalid(HARNESS_RUNTIME_ERROR_CODES.INVALID_QUESTION, 'question batch', {
+      reason: 'empty-question-batch',
+    });
+  }
+  const questions = values.map(defineQuestionSpec);
+  const duplicateId = questions.find((question, index) =>
+    questions.findIndex((candidate) => candidate.id === question.id) !== index);
+  if (duplicateId) {
+    invalid(HARNESS_RUNTIME_ERROR_CODES.INVALID_QUESTION, 'question batch', {
+      reason: 'duplicate-question-id',
+      questionId: duplicateId.id,
+    });
+  }
+  const duplicatePrompt = questions.find((question, index) =>
+    questions.findIndex((candidate) => candidate.prompt === question.prompt) !== index);
+  if (duplicatePrompt) {
+    invalid(HARNESS_RUNTIME_ERROR_CODES.INVALID_QUESTION, 'question batch', {
+      reason: 'duplicate-question-prompt',
+      questionId: duplicatePrompt.id,
+    });
+  }
+  return questions;
+}
+
+function validatePiQuestion(question) {
+  if (question.secret) {
+    throw new UnsupportedQuestionError('secret-input', { adapter: 'pi', questionId: question.id });
+  }
+  if (question.header.length > 16) {
+    throw new UnsupportedQuestionError('header-too-long', {
+      adapter: 'pi',
+      questionId: question.id,
+      maximum: 16,
+    });
+  }
+  if (question.options.length < 2 || question.options.length > 4) {
+    throw new UnsupportedQuestionError('option-count', {
+      adapter: 'pi',
+      questionId: question.id,
+      minimum: 2,
+      maximum: 4,
+    });
+  }
+  const duplicateLabel = question.options.find((option, index) =>
+    question.options.findIndex((candidate) => candidate.label === option.label) !== index);
+  if (duplicateLabel) {
+    invalid(HARNESS_RUNTIME_ERROR_CODES.INVALID_QUESTION, 'question', {
+      reason: 'duplicate-option-label',
+      questionId: question.id,
+      label: duplicateLabel.label,
+    });
+  }
+  validateNativeOptionLabels(question, 'pi');
+  for (const option of question.options) {
+    if (['Other', 'Type something.', 'Next'].includes(option.label)) {
+      throw new UnsupportedQuestionError('reserved-option-label', {
+        adapter: 'pi',
+        questionId: question.id,
+        optionId: option.id,
+        label: option.label,
+      });
+    }
+    if (option.description === undefined) {
+      throw new UnsupportedQuestionError('option-description-required', {
+        adapter: 'pi',
+        questionId: question.id,
+        optionId: option.id,
+      });
+    }
+    if (option.label.length > 60) {
+      throw new UnsupportedQuestionError('option-label-too-long', {
+        adapter: 'pi',
+        questionId: question.id,
+        optionId: option.id,
+        maximum: 60,
+      });
+    }
+  }
+}
+
+function chunk(values, size) {
+  const batches = [];
+  for (let index = 0; index < values.length; index += size) {
+    batches.push(values.slice(index, index + size));
+  }
+  return batches;
+}
+
+function batchingResult(calls) {
+  return {
+    required: calls.length > 1,
+    reason: calls.length > 1 ? 'adapter-capacity' : null,
+    callCount: calls.length,
+  };
+}
+
+function planPiQuestions(questions) {
+  for (const question of questions) validatePiQuestion(question);
+  const calls = chunk(questions, 4).map((batch, index) => ({
+    index,
+    questionIds: batch.map((question) => question.id),
+    answerMappings: answerMappings(batch),
+    payload: {
+      questions: batch.map((question) => ({
+        question: question.prompt,
+        header: question.header,
+        options: orderedQuestionOptions(question).map((option) => ({
+          label: option.label,
+          description: option.description,
+        })),
+        multiSelect: question.multiSelect,
+      })),
+    },
+  }));
+  return deepFreeze({
+    kind: 'native',
+    adapter: 'pi',
+    toolName: 'ask_user_question',
+    capacity: 4,
+    requiresMultipleCalls: calls.length > 1,
+    batching: batchingResult(calls),
+    calls,
+  });
+}
+
+function validateNativeOptions(question, adapter, maximum) {
+  if (question.options.length < 2 || question.options.length > maximum) {
+    throw new UnsupportedQuestionError('option-count', {
+      adapter,
+      questionId: question.id,
+      minimum: 2,
+      maximum,
+    });
+  }
+  const duplicateLabel = question.options.find((option, index) =>
+    question.options.findIndex((candidate) => candidate.label === option.label) !== index);
+  if (duplicateLabel) {
+    invalid(HARNESS_RUNTIME_ERROR_CODES.INVALID_QUESTION, 'question', {
+      reason: 'duplicate-option-label',
+      questionId: question.id,
+      label: duplicateLabel.label,
+    });
+  }
+  const missingDescription = question.options.find((option) => option.description === undefined);
+  if (missingDescription) {
+    throw new UnsupportedQuestionError('option-description-required', {
+      adapter,
+      questionId: question.id,
+      optionId: missingDescription.id,
+    });
+  }
+}
+
+function codexOptionLabel(question, option) {
+  return question.recommendationOrder[0] === option.id
+    ? `${option.label} (Recommended)`
+    : option.label;
+}
+
+function planCodexQuestions(questions) {
+  for (const question of questions) {
+    if (question.secret) {
+      throw new UnsupportedQuestionError('secret-input', {
+        adapter: 'codex',
+        questionId: question.id,
+      });
+    }
+    if (question.multiSelect) {
+      throw new UnsupportedQuestionError('multi-select', {
+        adapter: 'codex',
+        questionId: question.id,
+      });
+    }
+    if (!/^[a-z][a-z0-9_]*$/.test(question.id)) {
+      throw new UnsupportedQuestionError('invalid-question-id', {
+        adapter: 'codex',
+        questionId: question.id,
+        format: 'snake_case',
+      });
+    }
+    if (question.header.length > 12) {
+      throw new UnsupportedQuestionError('header-too-long', {
+        adapter: 'codex',
+        questionId: question.id,
+        maximum: 12,
+      });
+    }
+    validateNativeOptions(question, 'codex', 3);
+    validateNativeOptionLabels(question, 'codex', codexOptionLabel);
+  }
+  const calls = chunk(questions, 3).map((batch, index) => ({
+    index,
+    questionIds: batch.map((question) => question.id),
+    answerMappings: answerMappings(batch, codexOptionLabel),
+    payload: {
+      questions: batch.map((question) => ({
+        id: question.id,
+        header: question.header,
+        question: question.prompt,
+        options: orderedQuestionOptions(question).map((option) => ({
+          label: codexOptionLabel(question, option),
+          description: option.description,
+        })),
+      })),
+    },
+  }));
+  return deepFreeze({
+    kind: 'native',
+    adapter: 'codex',
+    toolName: 'request_user_input',
+    capacity: 3,
+    requiresMultipleCalls: calls.length > 1,
+    batching: batchingResult(calls),
+    calls,
+  });
+}
+
+function planClaudeQuestions(questions) {
+  for (const question of questions) {
+    if (question.secret) {
+      throw new UnsupportedQuestionError('secret-input', {
+        adapter: 'claude-code',
+        questionId: question.id,
+      });
+    }
+    if (question.header.length > 12) {
+      throw new UnsupportedQuestionError('header-too-long', {
+        adapter: 'claude-code',
+        questionId: question.id,
+        maximum: 12,
+      });
+    }
+    validateNativeOptions(question, 'claude-code', 4);
+    const nativeOptions = validateNativeOptionLabels(question, 'claude-code');
+    validateClaudeMultiAnswerFormats(question, nativeOptions);
+  }
+  const calls = chunk(questions, 4).map((batch, index) => ({
+    index,
+    questionIds: batch.map((question) => question.id),
+    answerMappings: answerMappings(batch),
+    payload: {
+      questions: batch.map((question) => ({
+        question: question.prompt,
+        header: question.header,
+        options: orderedQuestionOptions(question).map((option) => ({
+          label: option.label,
+          description: option.description,
+        })),
+        multiSelect: question.multiSelect,
+      })),
+    },
+  }));
+  return deepFreeze({
+    kind: 'native',
+    adapter: 'claude-code',
+    toolName: 'AskUserQuestion',
+    capacity: 4,
+    requiresMultipleCalls: calls.length > 1,
+    batching: batchingResult(calls),
+    calls,
+  });
+}
+
+function planQuestionFallback(capabilities, questions) {
+  const secret = questions.find((question) => question.secret);
+  if (secret) {
+    throw new UnsupportedQuestionError('secret-input', {
+      adapter: null,
+      questionId: secret.id,
+    });
+  }
+  const multiSelect = questions.find((question) => question.multiSelect);
+  if (multiSelect) {
+    throw new UnsupportedQuestionError('multi-select', {
+      adapter: null,
+      questionId: multiSelect.id,
+    });
+  }
+  const hasOptions = questions.some((question) => question.options.length > 0);
+  const oneFreeTextQuestion = questions.length === 1 && !hasOptions;
+  return deepFreeze({
+    kind: 'fallback',
+    adapter: null,
+    reason: 'no-supported-native-question-tool',
+    decision: oneFreeTextQuestion
+      ? 'concise-free-text'
+      : 'textual-multiple-choice-forbidden',
+    freeText: oneFreeTextQuestion
+      ? {
+        allowed: true,
+        questionId: questions[0].id,
+        prompt: questions[0].prompt,
+      }
+      : {
+        allowed: false,
+        reason: hasOptions ? 'logical-question-has-options' : 'multiple-questions',
+      },
+    textualMultipleChoice: {
+      allowed: false,
+      reason: QUESTION_FALLBACK_POLICY.noNativeQuestionTool.multipleChoice,
+    },
+    availableTools: clone(capabilities.nativeTools),
+  });
+}
+
+export function planStructuredQuestions(capabilitiesValue, questionValues) {
+  const capabilities = defineCurrentTurnCapabilities(capabilitiesValue);
+  const questions = validateQuestionBatch(questionValues);
+  if (capabilities.nativeTools.includes('ask_user_question')) {
+    return planPiQuestions(questions);
+  }
+  if (capabilities.nativeTools.includes('request_user_input')) {
+    return planCodexQuestions(questions);
+  }
+  if (capabilities.nativeTools.includes('AskUserQuestion')) {
+    return planClaudeQuestions(questions);
+  }
+  return planQuestionFallback(capabilities, questions);
+}
+
+function invalidAnswers(reason, details = {}) {
+  invalid(HARNESS_RUNTIME_ERROR_CODES.INVALID_ANSWERS, 'question answers', {
+    reason,
+    ...details,
+  });
+}
+
+function mappedOption(mapping, label) {
+  const matches = mapping.options.filter((option) => option.label === label);
+  if (matches.length > 1) {
+    invalidAnswers('ambiguous-option-label', {
+      questionId: mapping.questionId,
+      answer: label,
+      optionIds: matches.map((option) => option.id),
+    });
+  }
+  return matches[0];
+}
+
+function mapSingleAnswer(mapping, value, { custom = true } = {}) {
+  if (!nonEmptyString(value)) invalidAnswers('empty-answer', { questionId: mapping.questionId });
+  const option = mappedOption(mapping, value);
+  if (option) return option.id;
+  if (custom) return value;
+  invalidAnswers('unknown-option-label', { questionId: mapping.questionId, answer: value });
+}
+
+function requireCompleteAnswers(call, answers) {
+  const missingQuestionIds = call.answerMappings
+    .map((mapping) => mapping.questionId)
+    .filter((questionId) => !Object.hasOwn(answers, questionId));
+  if (missingQuestionIds.length > 0) {
+    invalidAnswers('incomplete-native-response', {
+      callIndex: call.index,
+      missingQuestionIds,
+    });
+  }
+  return answers;
+}
+
+function normalizePiResponse(call, response) {
+  if (!isRecord(response) || !isRecord(response.details)
+    || !Array.isArray(response.details.answers)
+    || response.details.cancelled !== false) {
+    invalidAnswers('malformed-pi-response', { callIndex: call.index });
+  }
+  const answers = {};
+  const seenIndexes = new Set();
+  for (const nativeAnswer of response.details.answers) {
+    if (!isRecord(nativeAnswer)
+      || !Number.isInteger(nativeAnswer.questionIndex)
+      || seenIndexes.has(nativeAnswer.questionIndex)) {
+      invalidAnswers('malformed-pi-answer', { callIndex: call.index });
+    }
+    const mapping = call.answerMappings[nativeAnswer.questionIndex];
+    if (!mapping || nativeAnswer.question !== mapping.prompt) {
+      invalidAnswers('unknown-pi-question', { callIndex: call.index });
+    }
+    seenIndexes.add(nativeAnswer.questionIndex);
+    if (nativeAnswer.kind === 'multi') {
+      if (!mapping.multiSelect
+        || !Array.isArray(nativeAnswer.selected)
+        || nativeAnswer.selected.length === 0
+        || !nativeAnswer.selected.every(nonEmptyString)) {
+        invalidAnswers('malformed-pi-multi-answer', { questionId: mapping.questionId });
+      }
+      answers[mapping.questionId] = nativeAnswer.selected.map((label) =>
+        mapSingleAnswer(mapping, label, { custom: false }));
+    } else if (nativeAnswer.kind === 'option') {
+      answers[mapping.questionId] = [
+        mapSingleAnswer(mapping, nativeAnswer.answer, { custom: false }),
+      ];
+    } else if (nativeAnswer.kind === 'custom') {
+      if (!nonEmptyString(nativeAnswer.answer)) {
+        invalidAnswers('empty-answer', { questionId: mapping.questionId });
+      }
+      answers[mapping.questionId] = [nativeAnswer.answer];
+    } else {
+      invalidAnswers('unknown-pi-answer-kind', { questionId: mapping.questionId });
+    }
+  }
+  return requireCompleteAnswers(call, answers);
+}
+
+function normalizeCodexResponse(call, response) {
+  if (!hasExactFields(response, ['answers']) || !isRecord(response.answers)) {
+    invalidAnswers('malformed-codex-response', { callIndex: call.index });
+  }
+  const mappings = new Map(call.answerMappings.map((mapping) => [mapping.questionId, mapping]));
+  const answers = {};
+  for (const [questionId, nativeAnswer] of Object.entries(response.answers)) {
+    const mapping = mappings.get(questionId);
+    if (!mapping || !hasExactFields(nativeAnswer, ['answers'])
+      || !stringList(nativeAnswer.answers, { allowEmpty: false })
+      || nativeAnswer.answers.length !== 1) {
+      invalidAnswers('malformed-codex-answer', { callIndex: call.index, questionId });
+    }
+    answers[questionId] = nativeAnswer.answers.map((value) => mapSingleAnswer(mapping, value));
+  }
+  return requireCompleteAnswers(call, answers);
+}
+
+function permutations(values) {
+  if (values.length === 0) return [[]];
+  return values.flatMap((value, index) =>
+    permutations(values.filter((_, candidateIndex) => candidateIndex !== index))
+      .map((rest) => [value, ...rest]));
+}
+
+function parseClaudeMultiAnswer(mapping, value) {
+  const matches = claudeMultiAnswerMappings(mapping.options)
+    .filter((candidate) => candidate.answer === value)
+    .map((candidate) => candidate.optionIds);
+  const unique = [...new Map(matches.map((match) => [JSON.stringify(match), match])).values()];
+  if (unique.length > 1) {
+    invalidAnswers('ambiguous-claude-multi-answer', { questionId: mapping.questionId });
+  }
+  return unique[0] ?? [value];
+}
+
+function normalizeClaudeResponse(call, response) {
+  if (!isRecord(response) || !isRecord(response.answers)) {
+    invalidAnswers('malformed-claude-response', { callIndex: call.index });
+  }
+  const mappings = new Map(call.answerMappings.map((mapping) => [mapping.prompt, mapping]));
+  const answers = {};
+  for (const [prompt, value] of Object.entries(response.answers)) {
+    const mapping = mappings.get(prompt);
+    if (!mapping || !nonEmptyString(value)) {
+      invalidAnswers('malformed-claude-answer', { callIndex: call.index, prompt });
+    }
+    answers[mapping.questionId] = mapping.multiSelect
+      ? parseClaudeMultiAnswer(mapping, value)
+      : [mapSingleAnswer(mapping, value)];
+  }
+  return requireCompleteAnswers(call, answers);
+}
+
+function responseCancelled(adapter, response) {
+  if (isRecord(response) && response.cancelled === true) return true;
+  return adapter === 'pi'
+    && isRecord(response)
+    && isRecord(response.details)
+    && response.details.cancelled === true;
+}
+
+export function normalizeQuestionResponses(plan, nativeResponses) {
+  if (!isRecord(plan) || plan.kind !== 'native'
+    || !['pi', 'codex', 'claude-code'].includes(plan.adapter)
+    || !Array.isArray(plan.calls)) {
+    invalidAnswers('invalid-question-plan');
+  }
+  if (!Array.isArray(nativeResponses) || nativeResponses.length !== plan.calls.length) {
+    invalidAnswers('response-count', {
+      expected: plan.calls.length,
+      actual: Array.isArray(nativeResponses) ? nativeResponses.length : null,
+    });
+  }
+  if (nativeResponses.some((response) => responseCancelled(plan.adapter, response))) {
+    return defineQuestionAnswers({});
+  }
+  const answers = {};
+  for (let index = 0; index < plan.calls.length; index += 1) {
+    const call = plan.calls[index];
+    const response = nativeResponses[index];
+    const normalized = plan.adapter === 'pi'
+      ? normalizePiResponse(call, response)
+      : plan.adapter === 'codex'
+        ? normalizeCodexResponse(call, response)
+        : normalizeClaudeResponse(call, response);
+    for (const [questionId, values] of Object.entries(normalized)) {
+      if (Object.hasOwn(answers, questionId)) {
+        invalidAnswers('duplicate-question-answer', { questionId });
+      }
+      answers[questionId] = values;
+    }
+  }
+  return defineQuestionAnswers(answers);
+}
+
+export function defineQuestionAnswers(value) {
+  if (!isRecord(value)
+    || Object.entries(value).some(([questionId, answers]) =>
+      !nonEmptyString(questionId) || !stringList(answers, { allowEmpty: false }))) {
+    invalid(HARNESS_RUNTIME_ERROR_CODES.INVALID_ANSWERS, 'question answers');
+  }
+  return deepFreeze(clone(value));
+}
+
+function validModel(model) {
+  return hasExactFields(model, ['id', 'sources'])
+    && nonEmptyString(model.id)
+    && stringList(model.sources, { allowEmpty: false });
+}
+
+export function defineModelAvailability(value) {
+  if (!hasExactFields(value, ['harness', 'completeness', 'models'])
+    || !HARNESSES.has(value.harness)
+    || !COMPLETENESS.has(value.completeness)
+    || !Array.isArray(value.models)
+    || !value.models.every(validModel)
+    || new Set(value.models.map((model) => model.id)).size !== value.models.length) {
+    invalid(HARNESS_RUNTIME_ERROR_CODES.INVALID_MODEL_AVAILABILITY, 'model availability');
+  }
+
+  const runtimeEnumerated = value.models.some((model) =>
+    model.sources.some((source) => RUNTIME_MODEL_SOURCES.has(source)));
+  if (value.completeness === 'full'
+    && ['codex', 'claude-code'].includes(value.harness)
+    && !runtimeEnumerated) {
+    invalid(
+      HARNESS_RUNTIME_ERROR_CODES.INVALID_MODEL_AVAILABILITY,
+      'model availability',
+      { reason: 'static-config-is-not-complete', harness: value.harness },
+    );
+  }
+
+  return deepFreeze(clone(value));
+}