Genarrative/packages/shared/src/contracts/creativeAgent.ts

import type { PuzzleResultDraft } from './puzzleAgentDraft';
import type { PuzzleAgentSessionSnapshot } from './puzzleAgentSession';
import type {
  PuzzleCreativeTemplateProtocol,
  PuzzleCreativeTemplateSelection,
  PuzzleDraftFieldPatch,
  PuzzleImageGenerationPlan,
  PuzzleTemplateCostRange,
} from './puzzleCreativeTemplate';

export type CreativeAgentStage =
  | 'idle'
  | 'perceiving'
  | 'thinking'
  | 'remembering'
  | 'selecting_puzzle_template'
  | 'waiting_template_confirmation'
  | 'planning_puzzle_levels'
  | 'acting'
  | 'reflecting'
  | 'collaborating'
  | 'target_ready'
  | 'waiting_user'
  | 'failed';

export type CreativeAgentEntryContext =
  | 'creation_home'
  | 'puzzle_workspace'
  | 'gallery_remix'
  | 'draft_restore';

export type CreativeAgentMessageRole = 'user' | 'assistant' | 'system';

export type CreativeAgentMessageKind =
  | 'chat'
  | 'stage'
  | 'action_result'
  | 'warning';

export type CreativeAgentInputPart =
  | {
      type: 'input_text';
      text: string;
    }
  | {
      type: 'input_image';
      imageUrl: string;
      assetId?: string | null;
      thumbnailUrl?: string | null;
    };

export interface CreativeImageInput {
  assetId: string;
  readUrl: string;
  thumbnailUrl?: string | null;
  width?: number | null;
  height?: number | null;
}

export interface CreativeImageSummary {
  assetId: string | null;
  readUrl: string | null;
  thumbnailUrl: string | null;
  width: number | null;
  height: number | null;
  summary: string | null;
}

export type CreativeUnsupportedPlayType =
  | 'rpg'
  | 'match3d'
  | 'big_fish'
  | 'square_hole';

export interface CreativeUnsupportedCapability {
  playType: CreativeUnsupportedPlayType;
  title: string;
  status: 'unsupported';
  reason: string;
}

export interface CreativeInputSummary {
  text: string | null;
  entryContext: CreativeAgentEntryContext;
  images: CreativeImageSummary[];
  materialSummary: string | null;
  unsupportedCapabilities: CreativeUnsupportedCapability[];
}

export interface CreativeAgentMessage {
  id: string;
  role: CreativeAgentMessageRole;
  kind: CreativeAgentMessageKind;
  text: string;
  createdAt: string;
}

export interface CreativeTargetSessionBinding {
  playType: 'puzzle';
  targetSessionId: string;
  targetStage: 'puzzle-agent-workspace' | 'puzzle-result' | 'puzzle-runtime';
  resultProfileId: string | null;
}

export interface CreativeAgentSessionSnapshot {
  sessionId: string;
  stage: CreativeAgentStage;
  inputSummary: CreativeInputSummary;
  messages: CreativeAgentMessage[];
  puzzleTemplateCatalog: PuzzleCreativeTemplateProtocol[];
  puzzleTemplateSelection: PuzzleCreativeTemplateSelection | null;
  puzzleImageGenerationPlan: PuzzleImageGenerationPlan | null;
  targetBinding: CreativeTargetSessionBinding | null;
  updatedAt: string;
}

export interface CreateCreativeAgentSessionRequest {
  text?: string | null;
  images?: CreativeImageInput[];
  entryContext?: CreativeAgentEntryContext;
}

export interface CreativeAgentSessionResponse {
  session: CreativeAgentSessionSnapshot;
}

export interface StreamCreativeAgentMessageRequest {
  clientMessageId: string;
  content: CreativeAgentInputPart[];
}

export interface ConfirmCreativePuzzleTemplateRequest {
  selection: PuzzleCreativeTemplateSelection;
}

export interface CreativeDraftEditStreamRequest {
  clientMessageId: string;
  instruction: string;
  targetPuzzleSessionId: string;
  currentDraft: PuzzleResultDraft;
}

export interface CreativeDraftEditResult {
  editInstructions: PuzzleDraftFieldPatch[];
  session: CreativeAgentSessionSnapshot;
  puzzleSession: PuzzleAgentSessionSnapshot;
}

export interface CreativeAgentStageEvent {
  sessionId: string;
  stage: CreativeAgentStage;
}

export interface CreativeAgentMessageDeltaEvent {
  sessionId: string;
  messageId: string;
  role: CreativeAgentMessageRole;
  kind: CreativeAgentMessageKind;
  textDelta: string;
}

export interface CreativeAgentThoughtSummaryDeltaEvent {
  sessionId: string;
  thoughtId: string;
  textDelta: string;
}

export interface CreativeAgentTemplateCatalogEvent {
  sessionId: string;
  templates: PuzzleCreativeTemplateProtocol[];
}

export interface CreativeAgentTemplateSelectionEvent {
  sessionId: string;
  selection: PuzzleCreativeTemplateSelection;
}

export interface CreativeAgentCostRangeEvent {
  sessionId: string;
  costRange: PuzzleTemplateCostRange;
}

export interface CreativeAgentLevelPlanEvent {
  sessionId: string;
  plan: PuzzleImageGenerationPlan;
}

export interface CreativeAgentToolEvent {
  sessionId: string;
  toolCallId: string;
  toolName: string;
  summary: string | null;
}

export interface CreativeAgentReflectionEvent {
  sessionId: string;
  pass: boolean;
  summary: string;
  warnings: string[];
}

export interface CreativeAgentTargetSessionEvent {
  sessionId: string;
  binding: CreativeTargetSessionBinding;
}

export interface CreativeAgentErrorEvent {
  sessionId: string | null;
  code: string;
  message: string;
  recoverable: boolean;
}

export interface CreativeAgentDoneEvent {
  sessionId: string;
}

export type CreativeAgentSseEvent =
  | { event: 'stage'; data: CreativeAgentStageEvent }
  | { event: 'agent_message_delta'; data: CreativeAgentMessageDeltaEvent }
  | {
      event: 'thought_summary_delta';
      data: CreativeAgentThoughtSummaryDeltaEvent;
    }
  | {
      event: 'puzzle_template_catalog';
      data: CreativeAgentTemplateCatalogEvent;
    }
  | {
      event: 'puzzle_template_selection';
      data: CreativeAgentTemplateSelectionEvent;
    }
  | { event: 'puzzle_cost_range'; data: CreativeAgentCostRangeEvent }
  | { event: 'puzzle_level_plan'; data: CreativeAgentLevelPlanEvent }
  | { event: 'tool_started'; data: CreativeAgentToolEvent }
  | { event: 'tool_completed'; data: CreativeAgentToolEvent }
  | { event: 'reflection'; data: CreativeAgentReflectionEvent }
  | { event: 'target_session'; data: CreativeAgentTargetSessionEvent }
  | {
      event: 'session';
      data: { session: CreativeAgentSessionSnapshot };
    }
  | { event: 'error'; data: CreativeAgentErrorEvent }
  | { event: 'done'; data: CreativeAgentDoneEvent };