makelore/shared/coding-teacher.ts

import type { TeacherDiscussion, TeacherDiscussionContent } from './teacher-discussion';
import type { PublicUsage } from './coding-conversation-contracts';

/** Only retained for locating conversations created by older clients. */
export type LegacyConsultationRole = 'teacher' | 'friend';
export const TEACHER_CHECK_IN_INTERVAL_MS = 5 * 60 * 1000;
export const TEACHER_UNCHANGED_CHECK_IN_INTERVAL_MS = 15 * 60 * 1000;
export type TeacherRequestIntent = 'question' | 'suggestions' | 'guided-help' | 'check-in';

export interface TeacherDefinition {
  config_id?: string;
  runtime?: 'local' | 'yuxi';
  yuxi?: { agent_slug: string; agent_version: number };
  schema_version: 1;
  teacher_id: string;
  name: string;
  description: string;
  avatar_id: string;
  welcome_message: string;
  suggested_questions: string[];
  system_prompt: string;
  skills: Array<{
    id: string;
    name: string;
    description: string;
    instructions_markdown: string;
    enabled: boolean;
  }>;
  model: {
    model_id: string | null;
    reasoning_choice:
      | { mode: 'default' | 'disabled'; effort?: null }
      | { mode: 'enabled'; effort?: string | null };
  };
  limits: { max_input_tokens: number; max_output_tokens: number };
}
export interface TeacherAvailability {
  enabled: boolean;
  published_version: number | null;
  revision: number;
}
export interface TeacherCatalog {
  items: Array<{ teacher_id: string; version: number; definition: TeacherDefinition; is_default: boolean }>;
}
export interface TeacherReference {
  kind: 'message' | 'code';
  text: string;
  messageId?: string;
  path?: string;
  startLine?: number;
}
export interface TeacherSourceMessage {
  id: string;
  role: 'user' | 'assistant';
  text: string;
}
export interface TeacherSourceContext {
  messages: TeacherSourceMessage[];
  cursor: { workerGeneration: number; seq: number; leafEntryId?: string };
  capturedAt: string;
}
export type TeacherRequestStatus =
  | 'preparing'
  | 'running'
  | 'completed'
  | 'failed'
  | 'cancelled'
  | 'interrupted';
export interface TeacherDiscussionContext {
  toolId: string;
  revision: number;
  focusId?: string;
  transition?: 'structure';
}
export interface TeacherDiscussionAction {
  toolId: string;
  revision: number;
  action: 'enter' | 'pause' | 'finish' | 'resume' | 'keep-idea' | 'aside-idea' | 'first-idea' | 'back-ideas';
  itemId?: string;
}
export interface TeacherRequest {
  presentation?: 'discussion-v1';
  discussionContext?: TeacherDiscussionContext;
  discussionSnapshot?: TeacherDiscussionContent;
  discussionError?: string;
  /** Original answer retained when discussion parsing fails; never fed back as context. */
  unparsedResponse?: string;
  toolActivity?: TeacherToolActivity[];

  intent?: TeacherRequestIntent;
  sourceConversationId?: string;
  /** Digest of completed source text, retained for check-in deduplication across restarts. */
  checkInSourceFingerprint?: string;
  id: string;
  text: string;
  references: TeacherReference[];
  createdAt: string;
  sourceCursor: TeacherSourceContext['cursor'];
  sourceCapturedAt: string;
  includedSourceMessageIds: string[];
  omittedMessages: number;
  truncatedMessages?: number;
  status: TeacherRequestStatus;
  response: string;
  suggestedQuestions?: string[];
  error?: string;
  usage?: PublicUsage;
  cloudRequestId?: string;
  progress?: string;
}
export interface TeacherToolActivity {
  id: string;
  name: string;
  status: 'running' | 'completed' | 'failed';
}
export interface TeacherTopic {
  discussion?: TeacherDiscussion;
  role?: LegacyConsultationRole;
  revision: number;
  schemaVersion: 1;
  id: string;
  accountId: string;
  projectId: string;
  sourceConversationId: string;
  version: number;
  draftRevision?: number;
  definition: TeacherDefinition;
  createdAt: string;
  updatedAt: string;
  requests: TeacherRequest[];
  unsaved?: boolean;
}
export interface TeacherTopicList {
  items: Array<{ id: string; title: string; updatedAt: string; version: number; teacherId?: string; legacyRole?: 'friend' }>;
  lastSelectedTopicId: string | null;
}
export interface TeacherSend {
  presentation?: 'discussion-v1';
  discussion?: TeacherDiscussionContext;
  intent?: TeacherRequestIntent;
  sourceConversationId?: string;
  requestId: string;
  text: string;
  references?: TeacherReference[];
}
export interface TeacherCheckInInput {
  requestId: string;
  sourceConversationId: string;
}
export interface TeacherCheckInResult {
  topic: TeacherTopic | null;
  skipped?: 'busy' | 'cooldown' | 'unchanged' | 'no-context' | 'archived' | 'disabled';
}