Codewalkers/src/agent/schema.ts

/**
 * Agent Output Schema
 *
 * Defines structured output schema for Claude agents using discriminated unions.
 * Replaces broken AskUserQuestion detection with explicit agent status signaling.
 *
 * Mode-specific schemas:
 * - execute: Standard task execution (done/questions/error)
 * - discuss: Gather context through questions, output decisions
 * - breakdown: Decompose initiative into phases
 */

import { z } from 'zod';

// =============================================================================
// SHARED SCHEMAS
// =============================================================================

/**
 * Option for questions - allows agent to present choices to user
 */
const optionSchema = z.object({
  label: z.string(),
  description: z.string().optional(),
});

/**
 * Individual question item with unique ID for answer matching
 */
export const questionItemSchema = z.object({
  id: z.string(),
  question: z.string(),
  options: z.array(optionSchema).optional(),
  multiSelect: z.boolean().optional(),
});

export type QuestionItem = z.infer<typeof questionItemSchema>;

/**
 * A decision captured during discussion.
 * Prompt instructs: { "topic": "Auth", "decision": "JWT", "reason": "Stateless" }
 */
const decisionSchema = z.object({
  topic: z.string(),
  decision: z.string(),
  reason: z.string(),
});

export type Decision = z.infer<typeof decisionSchema>;

/**
 * A phase from breakdown output.
 * Prompt instructs: { "number": 1, "name": "...", "description": "...", "dependencies": [0] }
 */
const phaseBreakdownSchema = z.object({
  number: z.number().int().positive(),
  name: z.string().min(1),
  description: z.string(),
  dependencies: z.array(z.number().int()).optional().default([]),
});

export type PhaseBreakdown = z.infer<typeof phaseBreakdownSchema>;

// =============================================================================
// EXECUTE MODE SCHEMA (default)
// =============================================================================

/**
 * Discriminated union for agent output in execute mode.
 *
 * Agent must return one of:
 * - done: Task completed successfully
 * - questions: Agent needs user input to continue (supports multiple questions)
 * - unrecoverable_error: Agent hit an error it cannot recover from
 */
export const agentOutputSchema = z.discriminatedUnion('status', [
  // Agent completed successfully
  z.object({
    status: z.literal('done'),
    result: z.string(),
    filesModified: z.array(z.string()).optional(),
  }),

  // Agent needs user input to continue (one or more questions)
  z.object({
    status: z.literal('questions'),
    questions: z.array(questionItemSchema),
  }),

  // Agent hit unrecoverable error
  z.object({
    status: z.literal('unrecoverable_error'),
    error: z.string(),
    attempted: z.string().optional(),
  }),
]);

export type AgentOutput = z.infer<typeof agentOutputSchema>;

/**
 * JSON Schema for --json-schema flag (convert Zod to JSON Schema).
 * This is passed to Claude CLI to enforce structured output.
 */
export const agentOutputJsonSchema = {
  type: 'object',
  oneOf: [
    {
      properties: {
        status: { const: 'done' },
        result: { type: 'string' },
        filesModified: { type: 'array', items: { type: 'string' } },
      },
      required: ['status', 'result'],
    },
    {
      properties: {
        status: { const: 'questions' },
        questions: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              id: { type: 'string' },
              question: { type: 'string' },
              options: {
                type: 'array',
                items: {
                  type: 'object',
                  properties: {
                    label: { type: 'string' },
                    description: { type: 'string' },
                  },
                  required: ['label'],
                },
              },
              multiSelect: { type: 'boolean' },
            },
            required: ['id', 'question'],
          },
        },
      },
      required: ['status', 'questions'],
    },
    {
      properties: {
        status: { const: 'unrecoverable_error' },
        error: { type: 'string' },
        attempted: { type: 'string' },
      },
      required: ['status', 'error'],
    },
  ],
};

// =============================================================================
// DISCUSS MODE SCHEMA
// =============================================================================

/**
 * Discuss mode output schema.
 * Agent asks questions OR completes with decisions.
 *
 * Prompt tells agent:
 * - Output "questions" status with questions array when needing input
 * - Output "context_complete" status with decisions array when done
 */
export const discussOutputSchema = z.discriminatedUnion('status', [
  // Agent needs more information
  z.object({
    status: z.literal('questions'),
    questions: z.array(questionItemSchema),
  }),
  // Agent has captured all decisions
  z.object({
    status: z.literal('context_complete'),
    decisions: z.array(decisionSchema),
    summary: z.string(), // Brief summary of all decisions
  }),
  // Unrecoverable error
  z.object({
    status: z.literal('unrecoverable_error'),
    error: z.string(),
  }),
]);

export type DiscussOutput = z.infer<typeof discussOutputSchema>;

/**
 * JSON Schema for discuss mode (passed to Claude CLI --json-schema)
 */
export const discussOutputJsonSchema = {
  type: 'object',
  oneOf: [
    {
      properties: {
        status: { const: 'questions' },
        questions: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              id: { type: 'string' },
              question: { type: 'string' },
              options: {
                type: 'array',
                items: {
                  type: 'object',
                  properties: {
                    label: { type: 'string' },
                    description: { type: 'string' },
                  },
                  required: ['label'],
                },
              },
              multiSelect: { type: 'boolean' },
            },
            required: ['id', 'question'],
          },
        },
      },
      required: ['status', 'questions'],
    },
    {
      properties: {
        status: { const: 'context_complete' },
        decisions: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              topic: { type: 'string' },
              decision: { type: 'string' },
              reason: { type: 'string' },
            },
            required: ['topic', 'decision', 'reason'],
          },
        },
        summary: { type: 'string' },
      },
      required: ['status', 'decisions', 'summary'],
    },
    {
      properties: {
        status: { const: 'unrecoverable_error' },
        error: { type: 'string' },
      },
      required: ['status', 'error'],
    },
  ],
};

// =============================================================================
// BREAKDOWN MODE SCHEMA
// =============================================================================

/**
 * Breakdown mode output schema.
 * Agent asks questions OR completes with phases.
 *
 * Prompt tells agent:
 * - Output "questions" status when needing clarification
 * - Output "breakdown_complete" status with phases array when done
 */
export const breakdownOutputSchema = z.discriminatedUnion('status', [
  // Agent needs clarification
  z.object({
    status: z.literal('questions'),
    questions: z.array(questionItemSchema),
  }),
  // Agent has decomposed initiative into phases
  z.object({
    status: z.literal('breakdown_complete'),
    phases: z.array(phaseBreakdownSchema),
  }),
  // Unrecoverable error
  z.object({
    status: z.literal('unrecoverable_error'),
    error: z.string(),
  }),
]);

export type BreakdownOutput = z.infer<typeof breakdownOutputSchema>;

/**
 * JSON Schema for breakdown mode (passed to Claude CLI --json-schema)
 */
export const breakdownOutputJsonSchema = {
  type: 'object',
  oneOf: [
    {
      properties: {
        status: { const: 'questions' },
        questions: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              id: { type: 'string' },
              question: { type: 'string' },
              options: {
                type: 'array',
                items: {
                  type: 'object',
                  properties: {
                    label: { type: 'string' },
                    description: { type: 'string' },
                  },
                  required: ['label'],
                },
              },
            },
            required: ['id', 'question'],
          },
        },
      },
      required: ['status', 'questions'],
    },
    {
      properties: {
        status: { const: 'breakdown_complete' },
        phases: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              number: { type: 'integer', minimum: 1 },
              name: { type: 'string', minLength: 1 },
              description: { type: 'string' },
              dependencies: {
                type: 'array',
                items: { type: 'integer' },
              },
            },
            required: ['number', 'name', 'description'],
          },
        },
      },
      required: ['status', 'phases'],
    },
    {
      properties: {
        status: { const: 'unrecoverable_error' },
        error: { type: 'string' },
      },
      required: ['status', 'error'],
    },
  ],
};