@fenixforce/edition-voices 0.1.0

package/dist/addon.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Voices Add-on — Loads teacher layer into a running Pro kernel.
+ *
+ * Pro keeps all existing tools (browser automation, skill marketplace, subagents).
+ * Teacher skills, platform API, and teaching loop are added alongside.
+ */
+import type { EditionManifest } from "./manifest.js";
+export interface FenixKernel {
+    manifest: EditionManifest;
+    systemPrompt: string;
+    toolRegistry: {
+        tool: (serverName: string, toolName: string, def: {
+            name: string;
+            description?: string;
+            handler: (input: any, ctx: any) => Promise<any>;
+        }) => void;
+        tools: () => Array<{
+            name: string;
+        }>;
+    };
+    httpServer: {
+        mount: (handler: (req: Request) => Promise<Response>) => void;
+    };
+    memory: {
+        registerCategories: (categories: string[]) => void;
+    };
+    events: {
+        emit: (event: string, data?: unknown) => void;
+    };
+}
+export interface VoicesAddonOptions {
+    kernel: FenixKernel;
+    licenseKey: string;
+}
+export interface VoicesAddonDeps {
+    validateLicense: (key: string) => Promise<boolean>;
+    runMigrations: (databaseUrl?: string) => Promise<void>;
+    createApiHandler: () => (req: Request) => Promise<Response>;
+    startScheduler: (learnerIds: string[]) => Promise<{
+        stop: () => void;
+    }>;
+    getActiveLearnerIds: () => Promise<string[]>;
+}
+export declare function validateLicenseKey(key: string, validate: (key: string) => Promise<boolean>): Promise<boolean>;
+export declare function loadVoicesAddon(options: VoicesAddonOptions, deps: VoicesAddonDeps): Promise<void>;

package/dist/api/platform-middleware.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Platform Middleware — API key validation, rate limiting, error formatting.
+ *
+ * All middleware operates on standard Request/Response objects and is
+ * framework-agnostic (works with Bun.serve, Express adapter, etc.).
+ */
+export interface ApiKeyRecord {
+    key: string;
+    name: string;
+    enabled: boolean;
+    rateLimit: number;
+}
+export interface RateLimitEntry {
+    count: number;
+    windowStart: number;
+}
+export interface PlatformMiddlewareDeps {
+    lookupApiKey: (key: string) => Promise<ApiKeyRecord | null>;
+}
+export interface ApiError {
+    error: string;
+    code: string;
+    details?: unknown;
+}
+export interface PaginationParams {
+    cursor?: string;
+    limit: number;
+}
+export interface PaginatedResponse<T> {
+    data: T[];
+    cursor: string | null;
+    hasMore: boolean;
+}
+export declare function parsePagination(url: URL, defaultLimit?: number, maxLimit?: number): PaginationParams;
+export declare function paginatedJson<T>(data: T[], limit: number, getCursor: (item: T) => string): Response;
+export declare function validateApiKey(request: Request, deps: PlatformMiddlewareDeps): Promise<ApiKeyRecord | Response>;
+export declare function checkKeyRateLimit(apiKey: string, maxPerMinute: number): Response | null;
+/** Reset rate limit store (for testing). */
+export declare function resetRateLimitStore(): void;
+export declare function errorResponse(status: number, code: string, message: string, details?: unknown): Response;
+export declare function jsonResponse(data: unknown, status?: number): Response;

package/dist/api/platform-routes.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Platform Routes — REST API endpoints for third-party integration.
+ *
+ * All routes are mounted under /api/v1 and require X-API-Key auth.
+ * List endpoints use cursor-based pagination.
+ */
+import type { LearnerProfile, LearnerPreferences } from "../teacher/learner-model.js";
+import type { Exercise } from "../teacher/exercises/generator.js";
+import { type PlatformMiddlewareDeps } from "./platform-middleware.js";
+export interface SessionRecord {
+    id: string;
+    learnerId: string;
+    exercises: Exercise[];
+    responses: ExerciseResponse[];
+    status: "active" | "completed";
+    summary?: SessionSummary;
+    startedAt: string;
+    completedAt?: string;
+}
+export interface ExerciseResponse {
+    exerciseId: string;
+    answer: string;
+    score: number;
+    feedback: string;
+}
+export interface SessionSummary {
+    totalExercises: number;
+    averageScore: number;
+    duration: number;
+}
+export interface ContentItem {
+    id: string;
+    language: string;
+    level: string;
+    type: string;
+    text: string;
+    tags: string[];
+}
+export interface LanguageInfo {
+    code: string;
+    name: string;
+    corpusSize: number;
+    learnerCount: number;
+}
+export interface PlatformRouteDeps extends PlatformMiddlewareDeps {
+    createLearner: (data: Partial<LearnerProfile>) => Promise<LearnerProfile>;
+    getLearner: (id: string) => Promise<LearnerProfile | null>;
+    updatePreferences: (id: string, prefs: Partial<LearnerPreferences>) => Promise<LearnerProfile>;
+    getProgress: (id: string) => Promise<unknown>;
+    getVocabulary: (id: string, cursor?: string, limit?: number) => Promise<ContentItem[]>;
+    getDueReviews: (id: string) => Promise<unknown>;
+    createSession: (learnerId: string) => Promise<SessionRecord>;
+    getSession: (id: string) => Promise<SessionRecord | null>;
+    submitResponse: (sessionId: string, exerciseId: string, answer: string) => Promise<ExerciseResponse>;
+    completeSession: (id: string) => Promise<SessionRecord>;
+    searchContent: (query: string, language?: string, level?: string, type?: string, cursor?: string, limit?: number) => Promise<ContentItem[]>;
+    addContent: (item: Partial<ContentItem>) => Promise<ContentItem>;
+    updateContent: (id: string, updates: Partial<ContentItem>) => Promise<ContentItem>;
+    importContent: (format: "csv" | "json", data: string) => Promise<{
+        imported: number;
+    }>;
+    listLanguages: () => Promise<LanguageInfo[]>;
+    getCurriculum: (code: string) => Promise<unknown | null>;
+    updateCurriculum: (code: string, data: unknown) => Promise<unknown>;
+    getLearnerAnalytics: (id: string) => Promise<unknown>;
+    getPlatformAnalytics: () => Promise<unknown>;
+}
+/**
+ * Create the platform API router.
+ */
+export declare function createPlatformRouter(deps: PlatformRouteDeps): (request: Request) => Promise<Response>;

package/dist/assessment/hardened-grader.d.ts

@@ -0,0 +1,76 @@
+export interface GradeCriteria {
+    semantic_accuracy: number;
+    grammatical_form: number;
+    pronunciation_match?: number;
+    response_latency_ok: boolean;
+    length_normalized: boolean;
+}
+export interface GradeResult {
+    criteria: GradeCriteria;
+    /** Weighted composite score (0.0–1.0) */
+    composite: number;
+    /** Hacking signals detected */
+    flags: string[];
+    /** Learner-facing explanation */
+    feedback: string;
+}
+export interface GradeInput {
+    /** Learner's response */
+    response: string;
+    /** Expected answer(s) */
+    expectedAnswers: string[];
+    /** The exercise prompt/question */
+    exercisePrompt: string;
+    /** Expected response length (characters) */
+    expectedLength: number;
+    /** Time taken to respond (ms) */
+    responseLatencyMs: number;
+    /** Whether this is a voice exercise */
+    isVoiceExercise: boolean;
+    /** Previous scores for this exercise (for consistency check) */
+    previousScores?: number[];
+}
+export interface GraderConfig {
+    /** Weight for semantic accuracy in composite */
+    weightSemantic: number;
+    /** Weight for grammatical form in composite */
+    weightGrammar: number;
+    /** Weight for pronunciation (voice only) */
+    weightPronunciation: number;
+    /** Max response/expected length ratio before penalty */
+    maxLengthRatio: number;
+    /** Minimum response latency before flagging (ms) */
+    minLatencyMs: number;
+    /** Penalty multiplier for excessive length */
+    lengthPenalty: number;
+}
+export declare const DEFAULT_GRADER_CONFIG: GraderConfig;
+export type SemanticScorerFn = (response: string, expectedAnswers: string[]) => Promise<number>;
+export type GrammarScorerFn = (response: string, languageCode: string) => Promise<number>;
+export type PronunciationScorerFn = (response: string, expected: string) => Promise<number>;
+export type FeedbackGeneratorFn = (criteria: GradeCriteria, flags: string[], exercisePrompt: string) => Promise<string>;
+export declare class HardenedGrader {
+    private config;
+    private scoreSemantic;
+    private scoreGrammar;
+    private scorePronunciation;
+    private generateFeedback;
+    constructor(deps: {
+        scoreSemantic: SemanticScorerFn;
+        scoreGrammar: GrammarScorerFn;
+        scorePronunciation?: PronunciationScorerFn;
+        generateFeedback: FeedbackGeneratorFn;
+    }, config?: Partial<GraderConfig>);
+    /**
+     * Grade a learner response with anti-hack defenses.
+     */
+    grade(input: GradeInput): Promise<GradeResult>;
+    /**
+     * Strip common cheating patterns from response.
+     */
+    private stripCheatingPatterns;
+    /**
+     * Compute weighted composite from criteria scores.
+     */
+    private computeComposite;
+}

package/dist/curriculum/zpd-selector.d.ts

@@ -0,0 +1,57 @@
+export interface ZPDWindow {
+    learnerId: string;
+    languageCode: string;
+    skillArea: string;
+    /** Highest fully mastered level (0–100) */
+    masteredLevel: number;
+    /** masteredLevel + stride */
+    stretchLevel: number;
+    /** masteredLevel + 2×stride — exercises above this cause abandonment */
+    abandonmentLevel: number;
+}
+export interface ZPDConfig {
+    /** Default stride (difficulty range above mastery) */
+    defaultStride: number;
+    /** Minimum stride (floor after repeated failures) */
+    minStride: number;
+    /** Sessions to look back for novelty filtering */
+    noveltyWindow: number;
+    /** Consecutive high-score threshold for boredom detection */
+    boredomThreshold: number;
+    /** Score threshold to count as "high" for boredom */
+    boredomScoreThreshold: number;
+}
+export declare const DEFAULT_ZPD_CONFIG: ZPDConfig;
+export interface SkillMastery {
+    skillArea: string;
+    masteryLevel: number;
+    stride: number;
+    recentScores: number[];
+}
+export interface ExerciseCandidate {
+    id: string;
+    skillArea: string;
+    difficulty: number;
+    topic: string;
+    lastSeenSessionIndex?: number;
+}
+export interface ZPDSelection {
+    candidates: ExerciseCandidate[];
+    zpdWindow: ZPDWindow;
+    strideAdjusted: boolean;
+}
+export type LearnerMasteryFn = (learnerId: string, languageCode: string) => Promise<SkillMastery[]>;
+export type ExerciseQueryFn = (languageCode: string, skillArea: string, minDifficulty: number, maxDifficulty: number) => Promise<ExerciseCandidate[]>;
+export type RecentExercisesFn = (learnerId: string, sessionCount: number) => Promise<Set<string>>;
+/**
+ * Compute the ZPD window for a skill area.
+ */
+export declare function computeZPDWindow(learnerId: string, languageCode: string, mastery: SkillMastery, config?: ZPDConfig): ZPDWindow;
+/**
+ * Select top-3 exercise candidates within the ZPD window.
+ */
+export declare function selectExercises(learnerId: string, languageCode: string, skillArea: string, getMastery: LearnerMasteryFn, queryExercises: ExerciseQueryFn, getRecentExercises: RecentExercisesFn, config?: ZPDConfig): Promise<ZPDSelection>;
+/**
+ * Update stride after an assessment score.
+ */
+export declare function adjustStride(currentStride: number, score: number, config?: ZPDConfig): number;

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Fenix Voices Edition — Voice-first agent with teacher layer
+ * for language learning, coaching, and conversational practice.
+ *
+ * Two deployment modes:
+ *   1. Standalone — `initVoicesStandalone()` boots the full Voices edition.
+ *   2. Kernel-integrated — `startVoices()` creates a kernel with teacher layers.
+ */
+import { createKernel, bootKernel, KERNEL_VERSION, type KernelConfig, type BootConfig, type Kernel, type RunningKernel, type EditionManifest as KernelEditionManifest } from "@fenixforce/kernel";
+import { type EditionManifest } from "./manifest.js";
+export declare const EDITION: "voices";
+export declare const VOICES_MANIFEST: KernelEditionManifest;
+export declare const VOICES_KERNEL_CONFIG: KernelConfig;
+export declare function startVoices(overrides?: Partial<KernelConfig>): Kernel;
+/** Boot a fully-wired Voices kernel with agent loop, providers, tools, and voice pipeline. */
+export declare function bootVoices(overrides?: Partial<BootConfig>): Promise<RunningKernel>;
+export { createKernel, bootKernel, KERNEL_VERSION };
+export interface VoicesConfig {
+    /** Postgres connection string. */
+    databaseUrl: string;
+    /** HTTP port for the platform API (default 3333). */
+    port?: number;
+    /** Voice defaults. */
+    ttsProvider?: string;
+    sttProvider?: string;
+    /** Speechmatics API key (for classroom STT with speaker focus). */
+    speechmaticsApiKey?: string;
+    /** Turn detection preset override (default: smart_turn for Voices). */
+    turnDetectionPreset?: "fast" | "fixed" | "adaptive" | "smart_turn" | "scribe" | "captions" | "external";
+    /** Workspace directory for speaker voiceprint persistence. */
+    workspaceDir?: string;
+}
+export interface VoicesInstance {
+    manifest: EditionManifest;
+    systemPrompt: string;
+    shutdown: () => Promise<void>;
+}
+export interface VoicesInitDeps {
+    runMigrations: (databaseUrl: string) => Promise<void>;
+    createToolRegistry: () => {
+        tool: (serverName: string, toolName: string, def: {
+            name: string;
+            description?: string;
+            handler: (input: any, ctx: any) => Promise<any>;
+        }) => void;
+        tools: () => Array<{
+            name: string;
+        }>;
+    };
+    mountApi: (port: number) => Promise<{
+        stop: () => void;
+    }>;
+    startScheduler: (learnerIds: string[]) => Promise<{
+        stop: () => void;
+    }>;
+    registerMemoryCategories: (categories: string[]) => void;
+    getActiveLearnerIds: () => Promise<string[]>;
+}
+export declare const VOICE_DEFAULTS: {
+    readonly ttsProvider: "fenix-tts";
+    readonly ttsdProvider: "fenix-ttsd";
+    readonly sttProvider: "groq-whisper";
+    /** Speechmatics for classroom scenarios with speaker focus + custom vocab */
+    readonly sttProviderClassroom: "speechmatics";
+    /** Turn detection: smart_turn for multi-speaker classroom */
+    readonly turnDetectionPreset: "smart_turn";
+};
+export declare function initVoicesStandalone(config: VoicesConfig, deps: VoicesInitDeps): Promise<VoicesInstance>;

package/dist/index.js

@@ -0,0 +1,54 @@
+import{createKernel as oe,bootKernel as le,KERNEL_VERSION as ke,EDITION_VOICES as ce}from"@fenixforce/kernel";var _={name:"fenix-voices",channels:["telegram","http-api","websocket","voice-telnyx","cli"],tools:["memory","web","files","schedule","curriculum","exercises","assessment","content-pipeline"],storage:"postgres",extensions:["default/*","voices/*"],features:{sandbox:!0,subagents:!0,teamMemory:!0,observability:!0,skillMarketplace:!1,teacherLayer:!0,teachingLoop:!0,contentPipeline:!0}};var j=`You are an autonomous language teacher powered by the Fenix Voices platform.
+Your goal is to help learners achieve fluency through structured, adaptive lessons.
+Be patient, encouraging, and culturally sensitive.`,H=`## Available Teacher Tools
+- **plan_lesson** \u2014 Create a lesson plan mixing new curriculum material with spaced-repetition reviews.
+- **placement_test** \u2014 Run an adaptive placement test to determine a learner's CEFR level.
+- **curriculum** \u2014 Browse and manage curriculum templates and units.
+- **exercises** \u2014 Generate exercises (vocabulary drill, fill-in-blank, translation, listening, pronunciation, dialogue roleplay, etc.).
+- **assessment** \u2014 Evaluate exercise responses, generate feedback, and produce session summaries.
+- **content-pipeline** \u2014 Import, tag, and manage corpus content (CSV, JSON, or web scraping via Scrapthing MCP).`,W=`## Learner Interaction Guidelines
+- Use the learner's target language progressively: start with simple phrases and increase as they advance.
+- Match your language complexity to the learner's CEFR level (pre-A1 through C2).
+- For levels pre-A1 to A2: use the bridge/native language for explanations, target language for practice.
+- For levels B1+: conduct most interaction in the target language.
+- Celebrate milestones and streaks to keep motivation high.
+- When the learner asks a general question, respond conversationally \u2014 only call plan_lesson when starting a structured practice session.`,G=`## When to Use Tools
+- **Starting a session**: Call plan_lesson to generate a structured lesson.
+- **First interaction with a new learner**: Call placement_test to assess their level.
+- **Learner submits an answer**: Use assessment to evaluate and provide feedback.
+- **Casual conversation**: Respond naturally without tool calls \u2014 use the target language when appropriate.
+- **Learner asks about their progress**: Retrieve stats from teacher memory.`;function B(){return[j,H,W,G].join(`
+
+`)}function L(e,t){let r=B();return t==="standalone"||!e?r:`${e}
+
+---
+
+${r}`}import{sql as m}from"kysely";async function d(e,t){let r=await m`
+    SELECT * FROM learner_profiles WHERE id = ${t}
+  `.execute(e);return r.rows[0]?w(r.rows[0]):null}async function v(e,t,r){let a=[],n=[];if(r.currentLevel!==void 0&&(a.push("current_level = $"+(n.length+1)),n.push(r.currentLevel)),r.bridgeLanguage!==void 0&&(a.push("bridge_language = $"+(n.length+1)),n.push(r.bridgeLanguage)),r.goals!==void 0&&(a.push("goals = $"+(n.length+1)+"::jsonb"),n.push(JSON.stringify(r.goals))),r.preferences!==void 0&&(a.push("preferences = $"+(n.length+1)+"::jsonb"),n.push(JSON.stringify(r.preferences))),r.stats!==void 0&&(a.push("stats = $"+(n.length+1)+"::jsonb"),n.push(JSON.stringify(r.stats))),a.length===0)return d(e,t);let s=await m`
+    UPDATE learner_profiles
+    SET ${m.raw(a.join(", "))}, updated_at = now()
+    WHERE id = ${t}
+    RETURNING *
+  `.execute(e);return s.rows[0]?w(s.rows[0]):null}async function S(e,t,r=20){let a=await m`
+    SELECT * FROM vocab_entries
+    WHERE learner_id = ${t} AND next_review_at <= now()
+    ORDER BY next_review_at ASC
+    LIMIT ${r}
+  `.execute(e),n=await m`
+    SELECT * FROM grammar_entries
+    WHERE learner_id = ${t} AND next_review_at <= now()
+    ORDER BY next_review_at ASC
+    LIMIT ${r}
+  `.execute(e);return{vocab:a.rows.map(k),grammar:n.rows.map(J)}}function w(e){return{id:e.id,userId:e.user_id,targetLanguage:e.target_language,nativeLanguage:e.native_language,bridgeLanguage:e.bridge_language??void 0,currentLevel:e.current_level,goals:e.goals??[],preferences:e.preferences??{},stats:e.stats??{},createdAt:new Date(e.created_at).toISOString(),updatedAt:new Date(e.updated_at).toISOString()}}function k(e){return{id:e.id,learnerId:e.learner_id,word:e.word,targetLanguage:e.target_language,translation:e.translation,mastery:e.mastery,nextReviewAt:new Date(e.next_review_at).toISOString(),reviewCount:e.review_count,lastReviewedAt:e.last_reviewed_at?new Date(e.last_reviewed_at).toISOString():void 0,context:e.context??void 0}}function J(e){return{id:e.id,learnerId:e.learner_id,concept:e.concept,targetLanguage:e.target_language,mastery:e.mastery,nextReviewAt:new Date(e.next_review_at).toISOString(),reviewCount:e.review_count,lastReviewedAt:e.last_reviewed_at?new Date(e.last_reviewed_at).toISOString():void 0,notes:e.notes??void 0}}import{sql as Z}from"kysely";import{readFileSync as N,readdirSync as Ne,existsSync as R}from"fs";import{join as E}from"path";var X=new Set(["pre-A1","A1","A2","B1","B2","C1","C2"]),Y=/^[a-z]{2,3}$/;function x(e){let t=[];if(!e||typeof e!="object")return t.push({path:"",message:"template must be an object"}),t;let r=e;if((!r.language||typeof r.language!="string"||!Y.test(r.language))&&t.push({path:"language",message:"must be a valid ISO 639 code"}),(!r.version||typeof r.version!="string")&&t.push({path:"version",message:"must be a string"}),!Array.isArray(r.units))return t.push({path:"units",message:"must be an array"}),t;let a=new Set;for(let n=0;n<r.units.length;n++){let s=r.units[n],i=`units[${n}]`;if(!s||typeof s!="object"){t.push({path:i,message:"must be an object"});continue}!s.id||typeof s.id!="string"?t.push({path:`${i}.id`,message:"must be a non-empty string"}):(a.has(s.id)&&t.push({path:`${i}.id`,message:`duplicate unit id: ${s.id}`}),a.add(s.id)),(!s.title||typeof s.title!="string")&&t.push({path:`${i}.title`,message:"must be a non-empty string"}),(!s.level||!X.has(s.level))&&t.push({path:`${i}.level`,message:"must be a valid CEFR level"}),Array.isArray(s.objectives)||t.push({path:`${i}.objectives`,message:"must be an array"}),Array.isArray(s.vocabularyTargets)||t.push({path:`${i}.vocabularyTargets`,message:"must be an array"}),Array.isArray(s.grammarTargets)||t.push({path:`${i}.grammarTargets`,message:"must be an array"}),Array.isArray(s.prerequisiteUnits)||t.push({path:`${i}.prerequisiteUnits`,message:"must be an array"}),(typeof s.estimatedSessions!="number"||s.estimatedSessions<1)&&t.push({path:`${i}.estimatedSessions`,message:"must be a positive number"}),(!s.exerciseTypeWeights||typeof s.exerciseTypeWeights!="object")&&t.push({path:`${i}.exerciseTypeWeights`,message:"must be an object"})}for(let n=0;n<r.units.length;n++){let s=r.units[n];if(Array.isArray(s.prerequisiteUnits))for(let i of s.prerequisiteUnits)a.has(i)||t.push({path:`units[${n}].prerequisiteUnits`,message:`references unknown unit: ${i}`})}return t}var A=E(process.cwd(),"data","curricula");function q(e,t=A){let r=E(t,`${e}.json`);if(!R(r)){let a=E(t,"sample.json");if(R(a))try{let n=N(a,"utf-8"),s=JSON.parse(n);if(s.language===e)return s}catch{}return null}try{let a=N(r,"utf-8"),n=JSON.parse(a);return x(n).length>0?null:n}catch{return null}}async function h(e,t,r=A){let a=await Z`
+    SELECT template FROM curriculum_templates WHERE language = ${t}
+  `.execute(e);return a.rows[0]?a.rows[0].template:q(t,r)}import{sql as O}from"kysely";async function T(e,t,r){let n=(await O`
+    SELECT * FROM learner_progress
+    WHERE learner_id = ${t} AND template_language = ${r}
+  `.execute(e)).rows[0];return n?z(n):null}async function U(e,t,r,a){return await O`
+    INSERT INTO learner_progress
+      (learner_id, template_language, current_unit_id, current_session, completed_units, unit_scores)
+    VALUES
+      (${t}, ${r}, ${a}, 1, '[]'::jsonb, '{}'::jsonb)
+    ON CONFLICT (learner_id, template_language) DO NOTHING
+  `.execute(e),await T(e,t,r)}function z(e){return{learnerId:e.learner_id,templateLanguage:e.template_language,completedUnits:e.completed_units??[],currentUnitId:e.current_unit_id,currentSession:e.current_session,unitScores:e.unit_scores??{}}}var Q=10,ee=30;function te(e){return{entryId:e.id,entryType:"vocab",word:e.word,lastScore:e.mastery}}function re(e){return{entryId:e.id,entryType:"grammar",concept:e.concept,lastScore:e.mastery}}function ne(e){return{"pre-A1":.1,A1:.2,A2:.35,B1:.5,B2:.65,C1:.8,C2:.95}[e]??.3}function I(e,t,r=6){let a=[],n=ne(e.level),s=e.exerciseTypeWeights,i=Object.values(s).reduce((o,l)=>o+l,0)||1;for(let[o,l]of Object.entries(s)){let g=Math.max(1,Math.round(l/i*r));for(let c=0;c<g&&a.length<r;c++)a.push({type:o,objective:e.objectives[a.length%e.objectives.length]??e.title,targetVocabulary:e.vocabularyTargets.length>0?e.vocabularyTargets.slice(0,3):void 0,targetGrammar:e.grammarTargets.length>0?e.grammarTargets.slice(0,2):void 0,contentQuery:`${e.title} ${e.level}`,difficulty:n})}return a}function b(e,t=8){return e.slice(0,t).map(r=>({type:r.entryType==="vocab"?"vocabulary_drill":"grammar_exercise",objective:`Review: ${r.word??r.concept??"item"}`,targetVocabulary:r.word?[r.word]:void 0,targetGrammar:r.concept?[r.concept]:void 0,difficulty:Math.max(.1,1-r.lastScore)}))}async function P(e,t){let{db:r}=e,a=await d(r,t);if(!a)throw new Error(`Learner not found: ${t}`);let n=await h(r,a.targetLanguage);if(!n&&e.generateTemplate&&(n=await e.generateTemplate(a.targetLanguage)),!n)throw new Error(`No curriculum template for language: ${a.targetLanguage}`);let s=await T(r,t,a.targetLanguage);if(!s){let u=n.units[0];if(!u)throw new Error("Curriculum has no units");s=await U(r,t,a.targetLanguage,u.id)}let i=n.units.find(u=>u.id===s.currentUnitId);if(!i)throw new Error(`Unit not found: ${s.currentUnitId}`);let o=await S(r,t,20),l=[...o.vocab.map(te),...o.grammar.map(re)],g=a.preferences?.sessionDuration??ee,c;if(l.length>=Q)c=b(l);else{let u=b(l,3),p=I(i,s.currentSession,6-u.length);c=[...u,...p]}return{learnerId:t,unitId:i.id,sessionNumber:s.currentSession,objectives:i.objectives,exercises:c,estimatedDuration:g,reviewItems:l}}var f={name:"plan_lesson",description:"Plan a language lesson for the current learner",handler:async(e,t)=>P(t.deps,e.learnerId)};var se=["pre-A1","A1","A2","B1","B2"],ae=.5,C=2;function $(e){let t="pre-A1";for(let r of e)r.passed&&(t=r.level);return t}function D(e){return e.length<C?!0:!e.slice(-C).every(r=>!r.passed)}async function F(e,t,r){let{db:a,generateExercises:n,scoreExercises:s,getResponses:i}=e,o=[];for(let g of se){if(!D(o))break;let c=await n(g,r);if(c.length===0)continue;let u=await i(c),p=await s(c,u),K=p>=ae;o.push({level:g,score:p,passed:K})}let l=$(o);return await v(a,t,{currentLevel:l}),{learnerId:t,testedLevels:o,assignedLevel:l}}var y={name:"placement_test",description:"Assess learner's current level in target language",handler:async(e,t)=>F(t.deps,e.learnerId,e.language)};var ie=[f,y];function M(e,t="teacher_skills"){for(let r of ie)e.tool(t,r.name,r)}var V="voices",Ze={...ce},ue={edition:V,channels:["telegram","web","voice"],tools:["*"],layers:["memory","knowledge-graph","teacher"]};function qe(e){return oe({...ue,...e})}async function ze(e){return le({edition:V,tools:["*"],maxTurns:20,...e})}var Qe={ttsProvider:"fenix-tts",ttsdProvider:"fenix-ttsd",sttProvider:"groq-whisper",sttProviderClassroom:"speechmatics",turnDetectionPreset:"smart_turn"};async function et(e,t){await t.runMigrations(e.databaseUrl);let r=t.createToolRegistry();M(r);let a=e.port??3333,n=await t.mountApi(a);t.registerMemoryCategories(["teacher:profile","teacher:vocab","teacher:grammar","teacher:session"]);let s=await t.getActiveLearnerIds(),i=await t.startScheduler(s),o=L(void 0,"standalone");return{manifest:_,systemPrompt:o,shutdown:async()=>{i.stop(),n.stop()}}}export{V as EDITION,ke as KERNEL_VERSION,ue as VOICES_KERNEL_CONFIG,Ze as VOICES_MANIFEST,Qe as VOICE_DEFAULTS,le as bootKernel,ze as bootVoices,oe as createKernel,et as initVoicesStandalone,qe as startVoices};

package/dist/manifest-merger.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Manifest Merger — Combines an add-on manifest into a running base manifest.
+ *
+ * - Tools: union (no duplicates)
+ * - Extensions: union (no duplicates)
+ * - Features: merge (addon overrides on conflict)
+ * - Channels: base channels unchanged
+ */
+import type { EditionManifest } from "./manifest.js";
+/**
+ * Merge an add-on manifest into a base manifest, returning a new combined manifest.
+ */
+export declare function mergeManifest(base: EditionManifest, addon: Partial<EditionManifest>): EditionManifest;

package/dist/manifest.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Voices Edition Manifests — Standalone and add-on configurations.
+ */
+export interface EditionManifest {
+    name: string;
+    channels: string[];
+    tools: string[];
+    storage: string;
+    extensions: string[];
+    features: Record<string, boolean>;
+}
+export declare const standaloneManifest: EditionManifest;
+export declare const addonManifest: Partial<EditionManifest>;

package/dist/memory/learner-diary.d.ts

@@ -0,0 +1,91 @@
+export interface LearnerDiaryEntry {
+    sessionId: string;
+    learnerId: string;
+    languageCode: string;
+    date: Date;
+    exercisesAttempted: number;
+    exercisesCompleted: number;
+    averageScore: number;
+    /** Error patterns seen 3+ times in the session */
+    persistentErrors: string[];
+    /** Exercises where score jumped 30%+ from recent average */
+    breakthroughMoments: string[];
+    engagementSignals: {
+        averageLatencyMs: number;
+        earlyExits: number;
+        /** Learner requested more exercises */
+        voluntaryExtensions: number;
+    };
+}
+export interface LearnerInsights {
+    learnerId: string;
+    languageCode: string;
+    synthesizedAt: Date;
+    /** Recurring error patterns across sessions */
+    persistentErrorPatterns: string[];
+    /** Skills where breakthroughs occurred */
+    breakthroughAreas: string[];
+    /** Engagement trend: improving, stable, declining */
+    engagementTrend: "improving" | "stable" | "declining";
+    /** Summary paragraph from LLM synthesis */
+    narrativeSummary: string;
+    /** Skill areas needing stride increase (from breakthroughs) */
+    strideBoostAreas: string[];
+}
+export interface DiaryConfig {
+    /** Number of entries to load for synthesis */
+    synthesisWindow: number;
+    /** Trigger synthesis after this many sessions */
+    synthesisThreshold: number;
+    /** Score jump percentage to count as breakthrough */
+    breakthroughJumpPercent: number;
+    /** Min occurrences of an error to count as persistent */
+    persistentErrorMin: number;
+}
+export declare const DEFAULT_DIARY_CONFIG: DiaryConfig;
+export type DiaryStoreFn = (entry: LearnerDiaryEntry) => Promise<void>;
+export type DiaryLoadFn = (learnerId: string, limit: number) => Promise<LearnerDiaryEntry[]>;
+export type InsightsStoreFn = (insights: LearnerInsights) => Promise<void>;
+export type SynthesisLLMFn = (prompt: string) => Promise<string>;
+export declare class LearnerDiary {
+    private config;
+    private store;
+    private load;
+    private storeInsights;
+    private llmSynthesize;
+    constructor(deps: {
+        store: DiaryStoreFn;
+        load: DiaryLoadFn;
+        storeInsights: InsightsStoreFn;
+        llmSynthesize: SynthesisLLMFn;
+    }, config?: Partial<DiaryConfig>);
+    /**
+     * Record a diary entry for a completed session.
+     */
+    recordSession(entry: LearnerDiaryEntry): Promise<void>;
+    /**
+     * Build a diary entry from raw session data.
+     */
+    buildEntry(sessionId: string, learnerId: string, languageCode: string, exercises: ExerciseRecord[], engagement: {
+        earlyExits: number;
+        voluntaryExtensions: number;
+    }): LearnerDiaryEntry;
+    /**
+     * Synthesize insights from recent diary entries.
+     * Run weekly or when session count crosses threshold.
+     */
+    synthesize(learnerId: string, languageCode: string): Promise<LearnerInsights>;
+    /**
+     * Format insights for injection into the teaching loop.
+     */
+    formatForContext(insights: LearnerInsights): string;
+}
+export interface ExerciseRecord {
+    exerciseId: string;
+    skillArea: string;
+    score: number;
+    completed: boolean;
+    errors: string[];
+    latencyMs: number;
+    previousAvgScore?: number;
+}

package/dist/system-prompt-patch.d.ts

@@ -0,0 +1,17 @@
+/**
+ * System Prompt Patch — Voices-specific system prompt additions.
+ *
+ * In standalone mode the patch IS the system prompt.
+ * In add-on mode the patch is appended to the existing Pro system prompt.
+ */
+/**
+ * Build the complete Voices system prompt patch.
+ */
+export declare function buildVoicesPromptPatch(): string;
+/**
+ * Apply the Voices patch to a system prompt.
+ *
+ * - Standalone: returns the patch as the full prompt.
+ * - Add-on: appends the patch to the existing Pro prompt.
+ */
+export declare function applyPromptPatch(existingPrompt: string | undefined, mode: "standalone" | "addon"): string;

package/dist/teacher/assessment/evaluator.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Exercise Evaluator — Scores exercise responses using deterministic
+ * matching where possible and LLM scoring for open-ended types.
+ */
+import type { LearnerProfile, CorrectionStyle } from "../learner-model.js";
+import type { Exercise, ExerciseType } from "../exercises/generator.js";
+export interface ExerciseResult {
+    exerciseId: string;
+    exerciseType: ExerciseType;
+    response: string;
+    score: number;
+    errors: ErrorClassification[];
+    feedback: string;
+    timeSpent: number;
+    hintsUsed: number;
+}
+export interface ErrorClassification {
+    type: "vocabulary" | "grammar" | "pronunciation" | "comprehension" | "spelling";
+    concept: string;
+    explanation: string;
+    severity: "minor" | "major";
+}
+export type LLMScoreFn = (exercise: Exercise, response: string, language: string) => Promise<{
+    score: number;
+    errors: ErrorClassification[];
+}>;
+export type LLMFeedbackFn = (exercise: Exercise, response: string, score: number, errors: ErrorClassification[], style: CorrectionStyle, language: string) => Promise<string>;
+export declare function scoreDeterministic(exercise: Exercise, response: string): number | null;
+export declare function wordOverlapScore(expected: string, actual: string): number;
+export declare function classifyBasicErrors(exercise: Exercise, response: string): ErrorClassification[];
+export interface EvaluateDeps {
+    llmScore?: LLMScoreFn;
+    llmFeedback?: LLMFeedbackFn;
+}
+export declare function evaluate(deps: EvaluateDeps, exercise: Exercise, response: string, learner: LearnerProfile, timeSpent?: number, hintsUsed?: number): Promise<ExerciseResult>;

package/dist/teacher/assessment/feedback-generator.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Feedback Generator — Generates teaching feedback matching the
+ * learner's correctionStyle preference.
+ *
+ * Three styles: gentle, direct, socratic.
+ */
+import type { CorrectionStyle } from "../learner-model.js";
+import type { Exercise } from "../exercises/generator.js";
+import type { ErrorClassification } from "./evaluator.js";
+export declare function buildFeedbackPrompt(exercise: Exercise, response: string, score: number, errors: ErrorClassification[], style: CorrectionStyle, language: string): string;
+export declare function generateLocalFeedback(score: number, errors: ErrorClassification[], style: CorrectionStyle, expectedAnswer?: string): string;

package/dist/teacher/assessment/session-summary.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Session Summary — End-of-session aggregation that updates the
+ * learner model, spaced repetition, and profile stats.
+ */
+import type { Kysely } from "kysely";
+import type { ExerciseResult } from "./evaluator.js";
+export interface SessionSummary {
+    sessionId: string;
+    learnerId: string;
+    duration: number;
+    exercisesCompleted: number;
+    averageScore: number;
+    newVocabulary: string[];
+    masteredItems: string[];
+    strugglingAreas: string[];
+    nextSessionFocus: string;
+    streakUpdate: {
+        current: number;
+        longest: number;
+    };
+}
+export declare function calculateStreak(lastSessionAt: string | undefined, currentStreak: number, longestStreak: number, now?: Date): {
+    current: number;
+    longest: number;
+};
+export declare function extractVocabulary(results: ExerciseResult[]): string[];
+export declare function findMasteredItems(results: ExerciseResult[]): string[];
+export declare function findStrugglingAreas(results: ExerciseResult[]): string[];
+export declare function determineNextFocus(strugglingAreas: string[], results: ExerciseResult[]): string;
+export interface SummarizeDeps {
+    db: Kysely<any>;
+}
+export declare function summarize(deps: SummarizeDeps, sessionId: string, learnerId: string, results: ExerciseResult[], startedAt: string, endedAt: string): Promise<SessionSummary>;