1

packages/shared/src/contracts/creativeAgent.ts

@@ -0,0 +1,244 @@
+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 };