@auxiora/personality 1.0.0

package/src/conversation-builder.ts

@@ -0,0 +1,279 @@
+import type { SoulConfig, ToneSettings } from './types.js';
+import { buildSoulMd } from './builder.js';
+import { scanAllStringFields } from './marketplace/scanner.js';
+
+export interface ConversationQuestion {
+  id: string;
+  text: string;
+  hint?: string;
+}
+
+export interface ConversationStep {
+  question: ConversationQuestion;
+  warning?: string;
+  done: false;
+}
+
+export interface ConversationComplete {
+  config: SoulConfig;
+  soulMd: string;
+  warnings?: string[];
+  done: true;
+}
+
+export type ConversationResult = ConversationStep | ConversationComplete;
+
+interface PartialConfig {
+  name?: string;
+  pronouns?: string;
+  errorStyle?: string;
+  humor?: number;
+  communicationStyle?: string;
+  expertise?: string[];
+  boundaries?: { neverJokeAbout: string[]; neverAdviseOn: string[] };
+  catchphrases?: Record<string, string>;
+}
+
+const NAME_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9 _-]{0,63}$/;
+
+const VALID_ERROR_STYLES = [
+  'professional',
+  'apologetic',
+  'matter_of_fact',
+  'self_deprecating',
+  'gentle',
+  'detailed',
+  'encouraging',
+  'terse',
+  'educational',
+];
+
+const QUESTIONS: ConversationQuestion[] = [
+  {
+    id: 'name',
+    text: 'What should I call myself? Pick a name for your AI assistant.',
+    hint: 'e.g. Nova, Atlas, Jasper, or any name you like',
+  },
+  {
+    id: 'error_style',
+    text: 'When I make a mistake or hit an error, how should I communicate it?',
+    hint: 'Options: professional, apologetic, matter_of_fact, self_deprecating, gentle, detailed, encouraging, terse, educational',
+  },
+  {
+    id: 'humor',
+    text: 'How much humor should I use? (0 = serious, 10 = maximum fun)',
+    hint: 'Enter a number from 0 to 10',
+  },
+  {
+    id: 'advice_boundaries',
+    text: 'Are there topics I should never give advice on? (comma-separated, or "none")',
+    hint: 'e.g. legal, medical, financial',
+  },
+  {
+    id: 'joke_boundaries',
+    text: 'Are there topics I should never joke about? (comma-separated, or "none")',
+    hint: 'e.g. health, politics, religion',
+  },
+  {
+    id: 'expertise',
+    text: 'What are my areas of expertise? (comma-separated, or "general")',
+    hint: 'e.g. TypeScript, DevOps, Python, Data Science',
+  },
+  {
+    id: 'catchphrases',
+    text: 'Any catchphrases you want me to use? Format: greeting=Hello there!, farewell=See ya! (or "none")',
+    hint: 'key=value pairs separated by commas',
+  },
+  {
+    id: 'communication_style',
+    text: 'Describe your preferred communication style in a few words.',
+    hint: 'e.g. warm and casual, formal and precise, brief and direct',
+  },
+];
+
+/** Check tone values for unusual combinations. */
+function checkToneCoherence(tone: ToneSettings): string[] {
+  const warnings: string[] = [];
+  if (tone.humor > 0.8 && tone.formality > 0.8) {
+    warnings.push('High humor + high formality is unusual. The result may feel inconsistent.');
+  }
+  if (tone.warmth < 0.2 && tone.humor > 0.6) {
+    warnings.push('Low warmth + high humor can come across as mean-spirited.');
+  }
+  if (tone.directness > 0.9 && tone.warmth > 0.9) {
+    warnings.push('Very direct + very warm can feel contradictory.');
+  }
+  return warnings;
+}
+
+export class SoulConversationBuilder {
+  private currentStep = 0;
+  private partial: PartialConfig = {};
+  private lastWarning?: string;
+
+  startConversation(): ConversationResult {
+    this.currentStep = 0;
+    this.partial = {};
+    this.lastWarning = undefined;
+    return {
+      question: QUESTIONS[0],
+      done: false,
+    };
+  }
+
+  processAnswer(answer: string): ConversationResult {
+    const questionId = QUESTIONS[this.currentStep].id;
+    this.lastWarning = undefined;
+    this.applyAnswer(questionId, answer.trim());
+    this.currentStep++;
+
+    if (this.currentStep >= QUESTIONS.length) {
+      const config = this.buildConfig();
+      const warnings = checkToneCoherence(config.tone);
+      return {
+        config,
+        soulMd: buildSoulMd(config),
+        warnings: warnings.length > 0 ? warnings : undefined,
+        done: true,
+      };
+    }
+
+    const step: ConversationStep = {
+      question: QUESTIONS[this.currentStep],
+      done: false,
+    };
+    if (this.lastWarning) {
+      step.warning = this.lastWarning;
+    }
+    return step;
+  }
+
+  getProgress(): number {
+    return Math.round((this.currentStep / QUESTIONS.length) * 100);
+  }
+
+  private applyAnswer(questionId: string, answer: string): void {
+    switch (questionId) {
+      case 'name':
+        if (answer && NAME_REGEX.test(answer)) {
+          this.partial.name = answer;
+        } else if (answer) {
+          this.partial.name = 'Auxiora';
+          this.lastWarning = `Name "${answer}" contains invalid characters. Using default "Auxiora".`;
+        } else {
+          this.partial.name = 'Auxiora';
+        }
+        break;
+
+      case 'error_style': {
+        const normalized = answer.toLowerCase().replace(/[\s-]/g, '_');
+        this.partial.errorStyle = VALID_ERROR_STYLES.includes(normalized) ? normalized : 'professional';
+        break;
+      }
+
+      case 'humor': {
+        const parsed = parseInt(answer, 10);
+        this.partial.humor = Number.isNaN(parsed) ? 0.3 : Math.max(0, Math.min(10, parsed)) / 10;
+        break;
+      }
+
+      case 'advice_boundaries': {
+        if (answer.toLowerCase() === 'none' || !answer) {
+          this.partial.boundaries = { ...this.partial.boundaries ?? { neverJokeAbout: [], neverAdviseOn: [] }, neverAdviseOn: [] };
+        } else {
+          const items = answer.split(',').map(s => s.trim()).filter(Boolean);
+          this.partial.boundaries = { ...this.partial.boundaries ?? { neverJokeAbout: [], neverAdviseOn: [] }, neverAdviseOn: items };
+        }
+        break;
+      }
+
+      case 'joke_boundaries': {
+        if (answer.toLowerCase() === 'none' || !answer) {
+          this.partial.boundaries = { ...this.partial.boundaries ?? { neverJokeAbout: [], neverAdviseOn: [] }, neverJokeAbout: [] };
+        } else {
+          const items = answer.split(',').map(s => s.trim()).filter(Boolean);
+          this.partial.boundaries = { ...this.partial.boundaries ?? { neverJokeAbout: [], neverAdviseOn: [] }, neverJokeAbout: items };
+        }
+        break;
+      }
+
+      case 'expertise': {
+        if (answer.toLowerCase() === 'general' || !answer) {
+          this.partial.expertise = [];
+        } else {
+          this.partial.expertise = answer.split(',').map(s => s.trim()).filter(Boolean);
+        }
+        break;
+      }
+
+      case 'catchphrases': {
+        if (answer.toLowerCase() === 'none' || !answer) {
+          this.partial.catchphrases = {};
+        } else {
+          const phrases: Record<string, string> = {};
+          const pairs = answer.split(',');
+          for (const pair of pairs) {
+            const eqIndex = pair.indexOf('=');
+            if (eqIndex > 0) {
+              const key = pair.slice(0, eqIndex).trim();
+              const value = pair.slice(eqIndex + 1).trim();
+              if (key && value) {
+                phrases[key] = value;
+              }
+            }
+          }
+
+          // Scan catchphrases for injection patterns
+          const scanResult = scanAllStringFields(phrases);
+          if (!scanResult.clean) {
+            this.partial.catchphrases = {};
+            this.lastWarning = 'Catchphrases contain disallowed patterns and were rejected.';
+          } else {
+            this.partial.catchphrases = phrases;
+          }
+        }
+        break;
+      }
+
+      case 'communication_style':
+        this.partial.communicationStyle = answer || 'balanced';
+        break;
+    }
+  }
+
+  private buildConfig(): SoulConfig {
+    const style = this.partial.communicationStyle?.toLowerCase() ?? 'balanced';
+    const tone = this.inferTone(style);
+
+    return {
+      name: this.partial.name ?? 'Auxiora',
+      pronouns: this.partial.pronouns ?? 'they/them',
+      tone: {
+        warmth: tone.warmth,
+        directness: tone.directness,
+        humor: this.partial.humor ?? 0.3,
+        formality: tone.formality,
+      },
+      expertise: this.partial.expertise ?? [],
+      errorStyle: this.partial.errorStyle ?? 'professional',
+      catchphrases: this.partial.catchphrases ?? {},
+      boundaries: this.partial.boundaries ?? { neverJokeAbout: [], neverAdviseOn: [] },
+    };
+  }
+
+  private inferTone(style: string): { warmth: number; directness: number; formality: number } {
+    if (/warm|friendly|casual/.test(style)) {
+      return { warmth: 0.8, directness: 0.5, formality: 0.2 };
+    }
+    if (/formal|precise|professional/.test(style)) {
+      return { warmth: 0.4, directness: 0.7, formality: 0.8 };
+    }
+    if (/brief|direct|concise/.test(style)) {
+      return { warmth: 0.4, directness: 0.9, formality: 0.5 };
+    }
+    if (/playful|fun/.test(style)) {
+      return { warmth: 0.9, directness: 0.4, formality: 0.1 };
+    }
+    return { warmth: 0.6, directness: 0.6, formality: 0.5 };
+  }
+}

package/src/escalation.ts

@@ -0,0 +1,162 @@
+/**
+ * Escalation state machine for response severity management.
+ * Tracks escalation level across a session and dampens personality tone accordingly.
+ */
+
+import type { ToneSettings } from './types.js';
+import { SecurityFloor } from './security-floor.js';
+
+export const ESCALATION_LEVELS = ['normal', 'caution', 'serious', 'lockdown'] as const;
+export type EscalationLevel = (typeof ESCALATION_LEVELS)[number];
+
+export const SEVERITY_LEVELS = ['low', 'medium', 'high', 'critical'] as const;
+export type SeverityLevel = (typeof SEVERITY_LEVELS)[number];
+
+export const RESPONSE_CATEGORIES = [
+  'uncertainty',
+  'access_failure',
+  'policy_block',
+  'destructive_confirmation',
+  'security_incident',
+  'rate_limit',
+  'provider_unavailable',
+  'partial_success',
+] as const;
+export type ResponseCategory = (typeof RESPONSE_CATEGORIES)[number];
+
+export interface EscalationTableEntry {
+  severity: SeverityLevel;
+  securityFloorRequired: boolean;
+  canonicalPhrase: string;
+}
+
+export const ESCALATION_TABLE: Record<ResponseCategory, EscalationTableEntry> = {
+  uncertainty: {
+    severity: 'low',
+    securityFloorRequired: false,
+    canonicalPhrase: "I don't have enough information to answer that confidently.",
+  },
+  access_failure: {
+    severity: 'medium',
+    securityFloorRequired: false,
+    canonicalPhrase: "I can't reach that resource right now.",
+  },
+  policy_block: {
+    severity: 'medium',
+    securityFloorRequired: true,
+    canonicalPhrase: 'That action is restricted by your configured policies.',
+  },
+  destructive_confirmation: {
+    severity: 'high',
+    securityFloorRequired: true,
+    canonicalPhrase: "This will [impact]. This cannot be undone. Type '[verb]' to confirm.",
+  },
+  security_incident: {
+    severity: 'critical',
+    securityFloorRequired: true,
+    canonicalPhrase: "I've detected something unusual. Here's what I see.",
+  },
+  rate_limit: {
+    severity: 'low',
+    securityFloorRequired: false,
+    canonicalPhrase: "I've hit a rate limit. I'll retry in [N] seconds.",
+  },
+  provider_unavailable: {
+    severity: 'medium',
+    securityFloorRequired: false,
+    canonicalPhrase: "My AI provider isn't responding. Trying fallback.",
+  },
+  partial_success: {
+    severity: 'low',
+    securityFloorRequired: false,
+    canonicalPhrase: "I completed part of that. Here's what worked and what didn't.",
+  },
+};
+
+export interface EscalationState {
+  level: EscalationLevel;
+  lastEvent?: ResponseCategory;
+  enteredAt?: number;
+}
+
+const SEVERITY_TO_LEVEL: Record<SeverityLevel, EscalationLevel> = {
+  low: 'caution',
+  medium: 'serious',
+  high: 'lockdown',
+  critical: 'lockdown',
+};
+
+const LEVEL_ORDER: Record<EscalationLevel, number> = {
+  normal: 0,
+  caution: 1,
+  serious: 2,
+  lockdown: 3,
+};
+
+export class EscalationStateMachine {
+  private state: EscalationState = { level: 'normal' };
+  private securityFloor = new SecurityFloor();
+
+  /** Process a response category event and transition escalation state. */
+  processEvent(event: ResponseCategory): EscalationState {
+    const entry = ESCALATION_TABLE[event];
+    const targetLevel = SEVERITY_TO_LEVEL[entry.severity];
+
+    // Only escalate upward, never downward from an event
+    if (LEVEL_ORDER[targetLevel] > LEVEL_ORDER[this.state.level]) {
+      this.state = {
+        level: targetLevel,
+        lastEvent: event,
+        enteredAt: Date.now(),
+      };
+    } else {
+      this.state = { ...this.state, lastEvent: event };
+    }
+
+    return { ...this.state };
+  }
+
+  /** Resolve toward normal. Transitions one step down. */
+  resolve(): EscalationState {
+    switch (this.state.level) {
+      case 'lockdown':
+        this.state = { level: 'normal', enteredAt: Date.now() };
+        break;
+      case 'serious':
+        this.state = { level: 'normal', enteredAt: Date.now() };
+        break;
+      case 'caution':
+        this.state = { level: 'normal', enteredAt: Date.now() };
+        break;
+      case 'normal':
+        break;
+    }
+    return { ...this.state };
+  }
+
+  /** Get current escalation state. */
+  getState(): EscalationState {
+    return { ...this.state };
+  }
+
+  /** Dampen tone values based on current escalation level. */
+  dampenTone(tone: ToneSettings): ToneSettings {
+    switch (this.state.level) {
+      case 'normal':
+        return { ...tone };
+      case 'caution':
+        return {
+          ...tone,
+          humor: tone.humor * 0.5,
+        };
+      case 'serious':
+        return {
+          ...tone,
+          humor: 0,
+          directness: Math.max(tone.directness, 0.6),
+        };
+      case 'lockdown':
+        return this.securityFloor.applyFloor(tone);
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,55 @@
+export type { PersonalityTemplate, SoulConfig, ToneSettings } from './types.js';
+export { parseSoulMd } from './parser.js';
+export { buildSoulMd } from './builder.js';
+export { PersonalityManager } from './manager.js';
+export { SoulConversationBuilder } from './conversation-builder.js';
+export type { ConversationQuestion, ConversationStep, ConversationComplete, ConversationResult } from './conversation-builder.js';
+// Modes system
+export { ModeLoader } from './modes/mode-loader.js';
+export { ModeDetector } from './modes/mode-detector.js';
+export { PromptAssembler } from './modes/prompt-assembler.js';
+export type {
+  ModeId,
+  ModeTemplate,
+  ModeSignal,
+  ModeDetectionResult,
+  UserPreferences,
+  SessionModeState,
+} from './modes/types.js';
+export { MODE_IDS, DEFAULT_PREFERENCES, DEFAULT_SESSION_MODE_STATE } from './modes/types.js';
+// [P15] Voice profiles
+export {
+  getVoiceProfile,
+  listVoiceProfiles,
+  DEFAULT_VOICE_PROFILE,
+  type VoiceProfile,
+} from './voice-profiles.js';
+// Security floor
+export { SecurityFloor, SECURITY_TOOL_PATTERNS, SECURITY_MESSAGE_PATTERNS } from './security-floor.js';
+export type { SecurityContext, SecurityFloorRule, SecurityDetectionInput } from './security-floor.js';
+// Escalation
+export {
+  EscalationStateMachine,
+  ESCALATION_LEVELS,
+  SEVERITY_LEVELS,
+  RESPONSE_CATEGORIES,
+  ESCALATION_TABLE,
+} from './escalation.js';
+export type {
+  EscalationLevel,
+  SeverityLevel,
+  ResponseCategory,
+  EscalationState,
+  EscalationTableEntry,
+} from './escalation.js';
+// Marketplace scanner
+export { scanString, scanAllStringFields, BLOCKED_PATTERNS } from './marketplace/scanner.js';
+export type { ScanViolation, ScanResult } from './marketplace/scanner.js';
+// Marketplace schema
+export {
+  validatePersonalityConfig,
+  PersonalityConfigSchema,
+  FORBIDDEN_FIELD_NAMES,
+  FORBIDDEN_FIELD_PATTERNS,
+} from './marketplace/schema.js';
+export type { ValidationResult } from './marketplace/schema.js';

package/src/manager.ts

@@ -0,0 +1,119 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import type { PersonalityTemplate, SoulConfig } from './types.js';
+import { parseSoulMd } from './parser.js';
+import { buildSoulMd } from './builder.js';
+
+export class PersonalityManager {
+  private templatesDir: string;
+  private workspaceDir: string;
+
+  constructor(templatesDir: string, workspaceDir: string) {
+    this.templatesDir = templatesDir;
+    this.workspaceDir = workspaceDir;
+  }
+
+  /**
+   * List all available personality templates from the templates directory.
+   */
+  async listTemplates(): Promise<PersonalityTemplate[]> {
+    let entries: string[];
+    try {
+      entries = await fs.readdir(this.templatesDir);
+    } catch {
+      return [];
+    }
+
+    const templates: PersonalityTemplate[] = [];
+    for (const entry of entries) {
+      if (!entry.endsWith('.md')) continue;
+      const template = await this.loadTemplateFile(entry);
+      if (template) templates.push(template);
+    }
+    return templates;
+  }
+
+  /**
+   * Get a specific personality template by ID.
+   */
+  async getTemplate(id: string): Promise<PersonalityTemplate | undefined> {
+    const filename = `${id}.md`;
+    return this.loadTemplateFile(filename);
+  }
+
+  /**
+   * Apply a template by copying its content to the workspace SOUL.md.
+   */
+  async applyTemplate(id: string): Promise<void> {
+    const template = await this.getTemplate(id);
+    if (!template) {
+      throw new Error(`Template not found: ${id}`);
+    }
+    // Inject template ID into frontmatter so we can identify it later
+    let content = template.soulContent;
+    content = content.replace(/^---\n/, `---\ntemplate: ${id}\n`);
+    const soulPath = path.join(this.workspaceDir, 'SOUL.md');
+    await fs.mkdir(this.workspaceDir, { recursive: true });
+    await fs.writeFile(soulPath, content, 'utf-8');
+  }
+
+  /**
+   * Read and parse the current SOUL.md from the workspace.
+   */
+  async getCurrentPersonality(): Promise<SoulConfig | undefined> {
+    const soulPath = path.join(this.workspaceDir, 'SOUL.md');
+    try {
+      const content = await fs.readFile(soulPath, 'utf-8');
+      return parseSoulMd(content);
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * Build a custom SOUL.md from a SoulConfig and write it to the workspace.
+   */
+  async buildCustom(config: SoulConfig, bodyMarkdown?: string): Promise<string> {
+    const content = buildSoulMd(config, bodyMarkdown);
+    const soulPath = path.join(this.workspaceDir, 'SOUL.md');
+    await fs.mkdir(this.workspaceDir, { recursive: true });
+    await fs.writeFile(soulPath, content, 'utf-8');
+    return content;
+  }
+
+  private async loadTemplateFile(filename: string): Promise<PersonalityTemplate | undefined> {
+    const filePath = path.join(this.templatesDir, filename);
+    let content: string;
+    try {
+      content = await fs.readFile(filePath, 'utf-8');
+    } catch {
+      return undefined;
+    }
+
+    const id = path.basename(filename, '.md');
+
+    // Extract template metadata from a comment block at the top before frontmatter
+    // Format: <!-- name: ...\n description: ...\n preview: ... -->
+    const metaMatch = content.match(/^<!--\s*([\s\S]*?)-->\s*\n/);
+    let name = id;
+    let description = '';
+    let preview = '';
+
+    if (metaMatch) {
+      const metaLines = metaMatch[1].split('\n');
+      for (const line of metaLines) {
+        const kv = line.match(/^\s*(\w+):\s*(.+)$/);
+        if (kv) {
+          const [, key, value] = kv;
+          if (key === 'name') name = value.trim();
+          else if (key === 'description') description = value.trim();
+          else if (key === 'preview') preview = value.trim();
+        }
+      }
+      // Remove the comment block from the soul content
+      content = content.slice(metaMatch[0].length);
+    }
+
+    return { id, name, description, preview, soulContent: content };
+  }
+}