agentic-orchestrator 0.1.28 → 0.2.1

package/apps/control-plane/src/application/services/question-service.ts

@@ -0,0 +1,693 @@
+import path from 'node:path';
+import { atomicWriteJson, ensureDir, nowIso, readJson, stableHash } from '../../core/fs.js';
+import { STATUS } from '../../core/constants.js';
+import { ERROR_CODES } from '../../core/error-codes.js';
+import type {
+  HumanInputStateSnapshot,
+  QuestionArtifact,
+  QuestionExpectedAnswer,
+  QuestionRecord,
+  QuestionStatus,
+  QuestionType,
+} from '../../core/questions.js';
+import { fail } from '../../core/response.js';
+
+type StateRecord = Record<string, unknown>;
+type QuestionAnswer = string | Record<string, unknown>;
+type TerminalStatus = 'merged' | 'failed' | 'paused_budget';
+type ResumableStatus = 'intake' | 'planning' | 'building' | 'qa' | 'blocked' | 'ready_to_merge';
+
+const DEFAULT_TIMEOUT_MS = 900_000;
+const DEFAULT_HISTORY_LIMIT = 3;
+const TERMINAL_STATUSES: ReadonlySet<TerminalStatus> = new Set([
+  STATUS.MERGED,
+  STATUS.FAILED,
+  STATUS.PAUSED_BUDGET,
+]);
+const RESUMABLE_STATUSES: ReadonlySet<ResumableStatus> = new Set([
+  STATUS.INTAKE,
+  STATUS.PLANNING,
+  STATUS.BUILDING,
+  STATUS.QA,
+  STATUS.BLOCKED,
+  STATUS.READY_TO_MERGE,
+]);
+const LEGAL_TRANSITIONS = new Map<string, Set<string>>([
+  [STATUS.INTAKE, new Set([STATUS.INTAKE, STATUS.PLANNING, STATUS.BLOCKED, STATUS.AWAITING_INPUT])],
+  [
+    STATUS.PLANNING,
+    new Set([STATUS.BUILDING, STATUS.BLOCKED, STATUS.AWAITING_INPUT, STATUS.PLANNING]),
+  ],
+  [STATUS.BUILDING, new Set([STATUS.QA, STATUS.BLOCKED, STATUS.AWAITING_INPUT, STATUS.BUILDING])],
+  [STATUS.QA, new Set([STATUS.READY_TO_MERGE, STATUS.BLOCKED, STATUS.AWAITING_INPUT, STATUS.QA])],
+  [
+    STATUS.READY_TO_MERGE,
+    new Set([STATUS.MERGED, STATUS.BLOCKED, STATUS.AWAITING_INPUT, STATUS.READY_TO_MERGE]),
+  ],
+  [
+    STATUS.BLOCKED,
+    new Set([
+      STATUS.PLANNING,
+      STATUS.BUILDING,
+      STATUS.QA,
+      STATUS.READY_TO_MERGE,
+      STATUS.AWAITING_INPUT,
+      STATUS.BLOCKED,
+    ]),
+  ],
+  [
+    STATUS.AWAITING_INPUT,
+    new Set([
+      STATUS.INTAKE,
+      STATUS.PLANNING,
+      STATUS.BUILDING,
+      STATUS.QA,
+      STATUS.BLOCKED,
+      STATUS.READY_TO_MERGE,
+      STATUS.AWAITING_INPUT,
+    ]),
+  ],
+  [STATUS.MERGED, new Set([STATUS.MERGED])],
+  [STATUS.FAILED, new Set([STATUS.FAILED, STATUS.BLOCKED])],
+]);
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return null;
+  }
+  return value as Record<string, unknown>;
+}
+
+function asString(value: unknown): string | null {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function asQuestionType(value: unknown): QuestionType {
+  if (
+    value === 'clarification' ||
+    value === 'permission_override' ||
+    value === 'external_decision' ||
+    value === 'risk_ack'
+  ) {
+    return value;
+  }
+  return 'clarification';
+}
+
+function asQuestionStatus(value: unknown): QuestionStatus | null {
+  if (value === 'open' || value === 'answered' || value === 'expired' || value === 'withdrawn') {
+    return value;
+  }
+  return null;
+}
+
+function readStateVersion(frontMatter: StateRecord): number {
+  const version = frontMatter.version;
+  return typeof version === 'number' && Number.isFinite(version) ? Math.floor(version) : 0;
+}
+
+function readStatus(frontMatter: StateRecord): string {
+  return typeof frontMatter.status === 'string' ? frontMatter.status : STATUS.INTAKE;
+}
+
+function isTerminalStatus(status: string): status is TerminalStatus {
+  return TERMINAL_STATUSES.has(status as TerminalStatus);
+}
+
+function isResumableStatus(status: string): status is ResumableStatus {
+  return RESUMABLE_STATUSES.has(status as ResumableStatus);
+}
+
+function normalizeExpectedAnswer(value: unknown): QuestionExpectedAnswer | null {
+  const record = asRecord(value);
+  if (!record) {
+    return null;
+  }
+  const kind = asString(record.kind);
+  if (!kind) {
+    return null;
+  }
+  const normalized: QuestionExpectedAnswer = { kind };
+  if (Array.isArray(record.choices)) {
+    normalized.choices = record.choices
+      .map((item) => asString(item))
+      .filter((item): item is string => item !== null);
+  }
+  const schema = asRecord(record.schema);
+  if (schema) {
+    normalized.schema = schema;
+  }
+  return normalized;
+}
+
+function normalizeAnswer(value: unknown): QuestionAnswer | null {
+  const stringValue = asString(value);
+  if (stringValue) {
+    return stringValue;
+  }
+  const record = asRecord(value);
+  return record ? record : null;
+}
+
+function isTransitionLegal(from: string, to: string): boolean {
+  return LEGAL_TRANSITIONS.get(from)?.has(to) ?? false;
+}
+
+function normalizeHumanInputState(value: unknown): HumanInputStateSnapshot {
+  const record = asRecord(value);
+  return {
+    open_question_id: asString(record?.open_question_id) ?? null,
+    open_question_count:
+      typeof record?.open_question_count === 'number' && Number.isFinite(record.open_question_count)
+        ? Math.max(0, Math.floor(record.open_question_count))
+        : 0,
+    awaiting_since: typeof record?.awaiting_since === 'string' ? record.awaiting_since : null,
+    requested_by_role: asString(record?.requested_by_role) ?? null,
+    prompt_summary: asString(record?.prompt_summary) ?? null,
+    resume_status: asString(record?.resume_status) ?? null,
+  };
+}
+
+function toPromptSummary(prompt: string): string {
+  const normalized = prompt.replace(/\s+/g, ' ').trim();
+  return normalized.length > 120 ? `${normalized.slice(0, 117)}...` : normalized;
+}
+
+function normalizeQuestionRecord(value: unknown): QuestionRecord | null {
+  const record = asRecord(value);
+  if (!record) {
+    return null;
+  }
+  const questionId = asString(record.question_id);
+  const status = asQuestionStatus(record.status);
+  const prompt = asString(record.prompt);
+  const role = asString(record.role);
+  const createdAt = asString(record.created_at);
+  if (!questionId || !status || !prompt || !role || !createdAt) {
+    return null;
+  }
+  return {
+    question_id: questionId,
+    status,
+    blocking: record.blocking !== false,
+    question_type: asQuestionType(record.question_type),
+    role,
+    phase: asString(record.phase) ?? readStatus(record),
+    request_action: asString(record.request_action) ?? 'ask_user_input',
+    session_id: asString(record.session_id) ?? 'unknown',
+    prompt,
+    details: asRecord(record.details) ?? {},
+    expected_answer: normalizeExpectedAnswer(record.expected_answer),
+    created_at: createdAt,
+    expires_at: typeof record.expires_at === 'string' ? record.expires_at : null,
+    answer: normalizeAnswer(record.answer),
+    answered_at: typeof record.answered_at === 'string' ? record.answered_at : null,
+    answered_by: asString(record.answered_by) ?? null,
+    resume_status: asString(record.resume_status) ?? null,
+    resume_phase: asString(record.resume_phase) ?? null,
+  };
+}
+
+function sortQuestions(items: QuestionRecord[]): QuestionRecord[] {
+  return [...items].sort((left, right) => {
+    if (left.created_at === right.created_at) {
+      return left.question_id.localeCompare(right.question_id);
+    }
+    return left.created_at.localeCompare(right.created_at);
+  });
+}
+
+function validateAnswer(record: QuestionRecord, answer: QuestionAnswer): boolean {
+  const expected = record.expected_answer;
+  if (!expected) {
+    return true;
+  }
+
+  if (expected.kind === 'single_choice') {
+    if (typeof answer !== 'string') {
+      return false;
+    }
+    const choices = Array.isArray(expected.choices) ? expected.choices : [];
+    return choices.length === 0 || choices.includes(answer);
+  }
+
+  if (expected.kind === 'free_text' || expected.kind === 'text') {
+    return typeof answer === 'string' && answer.trim().length > 0;
+  }
+
+  if (expected.kind === 'json') {
+    return typeof answer === 'object';
+  }
+
+  return true;
+}
+
+export interface QuestionServicePort {
+  withFeatureLock<T>(featureId: string, operation: () => Promise<T>): Promise<T>;
+  readState(featureId: string): Promise<{ frontMatter: StateRecord; body: string }>;
+  writeState(featureId: string, frontMatter: StateRecord, body?: string): Promise<void>;
+  questionsPath(featureId: string): string;
+  getPolicySnapshot(): Record<string, unknown>;
+}
+
+export interface QuestionCreateInput {
+  feature_id: string;
+  role: string;
+  session_id: string;
+  question_type?: string;
+  prompt: string;
+  details?: Record<string, unknown>;
+  expected_answer?: Record<string, unknown>;
+  blocking?: boolean;
+  phase?: string;
+  request_action?: string;
+  resume_status?: string;
+  resume_phase?: string;
+}
+
+export interface QuestionAnswerInput {
+  feature_id: string;
+  question_id: string;
+  answer: QuestionAnswer;
+  answered_by: string;
+}
+
+export class QuestionService {
+  private readonly port: QuestionServicePort;
+
+  constructor(port: QuestionServicePort) {
+    this.port = port;
+  }
+
+  private humanInputPolicy(): {
+    enabled: boolean;
+    timeoutMs: number;
+    maxOpenQuestionsPerFeature: number;
+    contextAnswerHistoryLimit: number;
+  } {
+    const execution = asRecord(this.port.getPolicySnapshot().execution);
+    const humanInput = asRecord(execution?.human_input);
+    return {
+      enabled: humanInput?.enabled !== false,
+      timeoutMs:
+        typeof humanInput?.timeout_ms === 'number' && Number.isFinite(humanInput.timeout_ms)
+          ? Math.max(1, Math.floor(humanInput.timeout_ms))
+          : DEFAULT_TIMEOUT_MS,
+      maxOpenQuestionsPerFeature:
+        typeof humanInput?.max_open_questions_per_feature === 'number' &&
+        Number.isFinite(humanInput.max_open_questions_per_feature)
+          ? Math.max(1, Math.floor(humanInput.max_open_questions_per_feature))
+          : 1,
+      contextAnswerHistoryLimit:
+        typeof humanInput?.context_answer_history_limit === 'number' &&
+        Number.isFinite(humanInput.context_answer_history_limit)
+          ? Math.max(1, Math.floor(humanInput.context_answer_history_limit))
+          : DEFAULT_HISTORY_LIMIT,
+    };
+  }
+
+  private async readQuestions(featureId: string): Promise<QuestionArtifact> {
+    const existing = await readJson(this.port.questionsPath(featureId), null);
+    const items = Array.isArray(existing?.items)
+      ? existing.items
+          .map((item: unknown) => normalizeQuestionRecord(item))
+          .filter((item: QuestionRecord | null): item is QuestionRecord => item !== null)
+      : [];
+    return {
+      version: 1,
+      feature_id: featureId,
+      items: sortQuestions(items),
+    };
+  }
+
+  private async writeQuestions(featureId: string, artifact: QuestionArtifact): Promise<void> {
+    await ensureDir(path.dirname(this.port.questionsPath(featureId)));
+    await atomicWriteJson(this.port.questionsPath(featureId), {
+      version: 1,
+      feature_id: featureId,
+      items: sortQuestions(artifact.items),
+    });
+  }
+
+  private buildQuestionId(featureId: string, role: string, prompt: string): string {
+    return `q_${stableHash(`${featureId}:${role}:${prompt}:${nowIso()}`).slice(0, 16)}`;
+  }
+
+  private normalizeStateForOpenQuestion(
+    frontMatter: StateRecord,
+    question: QuestionRecord,
+    at: string,
+  ): StateRecord {
+    const currentStatus = readStatus(frontMatter);
+    if (!isTransitionLegal(currentStatus, STATUS.AWAITING_INPUT)) {
+      throw {
+        normalizedResponse: fail(
+          ERROR_CODES.INVALID_STATUS_TRANSITION,
+          `Cannot transition ${currentStatus} to ${STATUS.AWAITING_INPUT}`,
+          {
+            from: currentStatus,
+            to: STATUS.AWAITING_INPUT,
+            retryable: false,
+            requires_human: true,
+          },
+        ),
+      };
+    }
+
+    return {
+      ...frontMatter,
+      version: readStateVersion(frontMatter) + 1,
+      status: STATUS.AWAITING_INPUT,
+      status_reason: `${ERROR_CODES.QUESTION_AWAITING_INPUT}:${question.question_id}`,
+      phase_entered_at: at,
+      last_updated: at,
+      human_input: {
+        open_question_id: question.question_id,
+        open_question_count: 1,
+        awaiting_since: at,
+        requested_by_role: question.role,
+        prompt_summary: toPromptSummary(question.prompt),
+        resume_status: question.resume_status,
+      } satisfies HumanInputStateSnapshot,
+      intake:
+        question.resume_status === STATUS.INTAKE
+          ? {
+              ...(asRecord(frontMatter.intake) ?? {}),
+              status: 'awaiting_input',
+            }
+          : frontMatter.intake,
+    };
+  }
+
+  private normalizeStateForAnsweredQuestion(
+    frontMatter: StateRecord,
+    question: QuestionRecord,
+    at: string,
+  ): StateRecord {
+    const {
+      activity_state: _activityState,
+      activity_last_event_at: _activityLastEventAt,
+      activity_detected_via: _activityDetectedVia,
+      activity_detector: _activityDetector,
+      ...normalizedFrontMatter
+    } = frontMatter;
+    const currentStatus = readStatus(frontMatter);
+    const requestedResume = question.resume_status;
+    const resumeStatus =
+      requestedResume && isResumableStatus(requestedResume) ? requestedResume : STATUS.PLANNING;
+    if (!isTransitionLegal(currentStatus, resumeStatus)) {
+      throw {
+        normalizedResponse: fail(
+          ERROR_CODES.INVALID_STATUS_TRANSITION,
+          `Cannot transition ${currentStatus} to ${resumeStatus}`,
+          { from: currentStatus, to: resumeStatus, retryable: false, requires_human: true },
+        ),
+      };
+    }
+
+    return {
+      ...normalizedFrontMatter,
+      version: readStateVersion(frontMatter) + 1,
+      status: resumeStatus,
+      status_reason:
+        resumeStatus === question.resume_status
+          ? `question_answered:${question.question_id}`
+          : `question_answered:${question.question_id}:resume_fallback_to_planning`,
+      phase_entered_at: at,
+      last_updated: at,
+      human_input: {
+        open_question_id: null,
+        open_question_count: 0,
+        awaiting_since: null,
+        requested_by_role: null,
+        prompt_summary: null,
+        resume_status: null,
+      } satisfies HumanInputStateSnapshot,
+      intake:
+        resumeStatus === STATUS.INTAKE
+          ? {
+              ...(asRecord(frontMatter.intake) ?? {}),
+              status: 'in_progress',
+            }
+          : frontMatter.intake,
+    };
+  }
+
+  async questionCreate(input: QuestionCreateInput): Promise<{
+    data: {
+      question_id: string;
+      status: QuestionStatus;
+      feature_status: string;
+      resume_status: string | null;
+    };
+  }> {
+    const policy = this.humanInputPolicy();
+    if (!policy.enabled) {
+      throw {
+        normalizedResponse: fail(
+          ERROR_CODES.INVALID_ARGUMENT,
+          'human input is disabled by policy',
+          {
+            retryable: false,
+            requires_human: true,
+          },
+        ),
+      };
+    }
+
+    return await this.port.withFeatureLock(input.feature_id, async () => {
+      const state = await this.port.readState(input.feature_id);
+      const currentStatus = readStatus(state.frontMatter);
+      if (isTerminalStatus(currentStatus)) {
+        throw {
+          normalizedResponse: fail(
+            ERROR_CODES.QUESTION_ANSWER_NOT_ALLOWED_IN_TERMINAL_STATE,
+            `Cannot open question for terminal feature state ${currentStatus}`,
+            {
+              feature_id: input.feature_id,
+              status: currentStatus,
+              retryable: false,
+              requires_human: true,
+            },
+          ),
+        };
+      }
+
+      const artifact = await this.readQuestions(input.feature_id);
+      const openQuestions = artifact.items.filter(
+        (item) => item.status === 'open' && item.blocking,
+      );
+      if (openQuestions.length >= policy.maxOpenQuestionsPerFeature) {
+        throw {
+          normalizedResponse: fail(
+            ERROR_CODES.QUESTION_CONFLICT_OPEN,
+            `Feature ${input.feature_id} already has an open blocking question`,
+            { feature_id: input.feature_id, retryable: false, requires_human: true },
+          ),
+        };
+      }
+
+      const at = nowIso();
+      const requestedResumeStatus = asString(input.resume_status);
+      const requestedResumePhase = asString(input.resume_phase);
+      const resumeStatus =
+        requestedResumeStatus && isResumableStatus(requestedResumeStatus)
+          ? requestedResumeStatus
+          : isResumableStatus(currentStatus)
+            ? currentStatus
+            : STATUS.PLANNING;
+      const resumePhase =
+        requestedResumePhase && isResumableStatus(requestedResumePhase)
+          ? requestedResumePhase
+          : resumeStatus;
+      const question: QuestionRecord = {
+        question_id: this.buildQuestionId(input.feature_id, input.role, input.prompt),
+        status: 'open',
+        blocking: input.blocking !== false,
+        question_type: asQuestionType(input.question_type),
+        role: input.role,
+        phase: asString(input.phase) ?? currentStatus,
+        request_action: asString(input.request_action) ?? 'ask_user_input',
+        session_id: input.session_id,
+        prompt: input.prompt,
+        details: input.details ?? {},
+        expected_answer: normalizeExpectedAnswer(input.expected_answer) ?? null,
+        created_at: at,
+        expires_at: new Date(Date.parse(at) + policy.timeoutMs).toISOString(),
+        answer: null,
+        answered_at: null,
+        answered_by: null,
+        resume_status: resumeStatus,
+        resume_phase: resumePhase,
+      };
+
+      artifact.items.push(question);
+      await this.writeQuestions(input.feature_id, artifact);
+      await this.port.writeState(
+        input.feature_id,
+        this.normalizeStateForOpenQuestion(state.frontMatter, question, at),
+        state.body,
+      );
+
+      return {
+        data: {
+          question_id: question.question_id,
+          status: question.status,
+          feature_status: STATUS.AWAITING_INPUT,
+          resume_status: question.resume_status,
+        },
+      };
+    });
+  }
+
+  async questionList(
+    featureId: string,
+    status: QuestionStatus | 'all' = 'open',
+  ): Promise<{ data: { items: QuestionRecord[] } }> {
+    const artifact = await this.readQuestions(featureId);
+    const items =
+      status === 'all' ? artifact.items : artifact.items.filter((item) => item.status === status);
+    return { data: { items } };
+  }
+
+  async questionAnswer(input: QuestionAnswerInput): Promise<{
+    data: {
+      feature_id: string;
+      question_id: string;
+      question_status: QuestionStatus;
+      feature_status: string;
+      resume_status: string | null;
+      resumed: boolean;
+    };
+  }> {
+    return await this.port.withFeatureLock(input.feature_id, async () => {
+      const state = await this.port.readState(input.feature_id);
+      const currentStatus = readStatus(state.frontMatter);
+      if (isTerminalStatus(currentStatus)) {
+        throw {
+          normalizedResponse: fail(
+            ERROR_CODES.QUESTION_ANSWER_NOT_ALLOWED_IN_TERMINAL_STATE,
+            `Cannot answer question for terminal feature state ${currentStatus}`,
+            {
+              feature_id: input.feature_id,
+              status: currentStatus,
+              retryable: false,
+              requires_human: true,
+            },
+          ),
+        };
+      }
+
+      const artifact = await this.readQuestions(input.feature_id);
+      const answer = normalizeAnswer(input.answer);
+      if (!answer) {
+        throw {
+          normalizedResponse: fail(
+            ERROR_CODES.QUESTION_ANSWER_INVALID,
+            'Question answer is required',
+            {
+              retryable: false,
+              requires_human: true,
+            },
+          ),
+        };
+      }
+
+      const questionIndex = artifact.items.findIndex(
+        (item) => item.question_id === input.question_id,
+      );
+      if (questionIndex === -1) {
+        throw {
+          normalizedResponse: fail(ERROR_CODES.QUESTION_NOT_FOUND, 'Question not found', {
+            feature_id: input.feature_id,
+            question_id: input.question_id,
+            retryable: false,
+            requires_human: true,
+          }),
+        };
+      }
+
+      const question = artifact.items[questionIndex];
+      if (question.status !== 'open') {
+        throw {
+          normalizedResponse: fail(
+            ERROR_CODES.QUESTION_ALREADY_CLOSED,
+            'Question is already closed',
+            {
+              feature_id: input.feature_id,
+              question_id: input.question_id,
+              status: question.status,
+              retryable: false,
+              requires_human: false,
+            },
+          ),
+        };
+      }
+      if (!validateAnswer(question, answer)) {
+        throw {
+          normalizedResponse: fail(
+            ERROR_CODES.QUESTION_ANSWER_INVALID,
+            'Question answer does not match the expected answer contract',
+            {
+              feature_id: input.feature_id,
+              question_id: input.question_id,
+              expected_answer: question.expected_answer,
+              retryable: false,
+              requires_human: true,
+            },
+          ),
+        };
+      }
+
+      const at = nowIso();
+      const answered: QuestionRecord = {
+        ...question,
+        status: 'answered',
+        answer,
+        answered_at: at,
+        answered_by: input.answered_by,
+      };
+      artifact.items[questionIndex] = answered;
+      await this.writeQuestions(input.feature_id, artifact);
+      const nextState = this.normalizeStateForAnsweredQuestion(state.frontMatter, answered, at);
+      await this.port.writeState(input.feature_id, nextState, state.body);
+
+      return {
+        data: {
+          feature_id: input.feature_id,
+          question_id: answered.question_id,
+          question_status: answered.status,
+          feature_status: readStatus(nextState),
+          resume_status: answered.resume_status,
+          resumed: readStatus(nextState) !== STATUS.AWAITING_INPUT,
+        },
+      };
+    });
+  }
+
+  async questionContext(featureId: string): Promise<{
+    open_questions: QuestionRecord[];
+    latest_answer: QuestionRecord | null;
+  }> {
+    const policy = this.humanInputPolicy();
+    const artifact = await this.readQuestions(featureId);
+    const openQuestions = artifact.items.filter((item) => item.status === 'open');
+    const answered = artifact.items
+      .filter((item) => item.status === 'answered' && item.answered_at)
+      .sort((left, right) => (right.answered_at ?? '').localeCompare(left.answered_at ?? ''))
+      .slice(0, policy.contextAnswerHistoryLimit);
+    return {
+      open_questions: openQuestions,
+      latest_answer: answered[0] ?? null,
+    };
+  }
+
+  async questionSummary(featureId: string): Promise<HumanInputStateSnapshot> {
+    const state = await this.port.readState(featureId);
+    return normalizeHumanInputState(state.frontMatter.human_input);
+  }
+}