makelore/shared/coding-teacher.ts

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 TeacherShortcut {
  label: string;
  prompt: string;
}

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;
  icon_url?: string | null;
  welcome_message: string;
  suggested_questions: string[];
  shortcuts?: TeacherShortcut[] | null;
  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 {
  revision?: number;
  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 TeacherRequest {
  /** Frozen when this turn is accepted; history can span projects and releases. */
  projectId?: string;
  projectName?: string;
  teacherVersion?: number;
  /** Explicit per-question model; absent follows the published teacher configuration. */
  modelId?: string;
  runtimeThreadId?: string;
  origin?: { projectId: string; topicId: string; requestId: string };
  /** discussion-v1 is retained only to identify historical replies. */
  presentation?: 'reply-v1' | 'discussion-v1';
  /** Archived legacy data; never parsed into interactive component state. */
  discussionContext?: unknown;
  discussionSnapshot?: unknown;
  discussionError?: string;
  replyParseError?: string;
  /** No trustworthy complete reply could be recovered from the received text. */
  replyIncomplete?: boolean;
  /** New-output shortcut rejection survives later historical prose repair. */
  replyQuickRepliesRejected?: boolean;
  /** Original answer retained for failed or repaired parsing; never fed back as context. */
  unparsedResponse?: string;
  toolActivity?: TeacherToolActivity[];
  /** Provider-emitted main-thread reasoning, separate from the answer/context. */
  reasoning?: string;

  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;
  /** Actual terminal time, absent in older history; never inferred from topic.updatedAt. */
  finishedAt?: 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 {
  /** Present only for the continuous conversation owned by this account + project + agent. */
  conversation?: {
    agentId: string;
    runtimeThreadId?: string;
    segmentTurns: number;
    /** Archived per-project component data; never selected or updated by new turns. */
    discussions?: Record<string, unknown>;
    seenThrough?: string;
  };
  /** Archived legacy data; new requests do not create or update it. */
  discussion?: unknown;
  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'; legacySourceId?: string }>;
  lastSelectedTopicId: string | null;
}
export interface TeacherModelCatalog {
  supported: boolean;
  models: Array<{ id: string }>;
  message?: string;
}
export interface TeacherSend {
  modelId?: string;
  projectId?: string;
  intent?: TeacherRequestIntent;
  sourceConversationId?: string;
  requestId: string;
  text: string;
  references?: TeacherReference[];
}
export interface TeacherHistoryPage {
  requests: TeacherRequest[];
  before: string | null;
}
export interface TeacherConversationView {
  topic: TeacherTopic | null;
  before: string | null;
}
export interface TeacherCheckInInput {
  requestId: string;
  sourceConversationId: string;
}
export interface TeacherCheckInResult {
  topic: TeacherTopic | null;
  skipped?: 'busy' | 'cooldown' | 'unchanged' | 'no-context' | 'archived' | 'disabled';
}