@happyvertical/smrt-education 0.57.47 → 0.57.49

package/dist/tutor-context-service.d.ts

@@ -0,0 +1,34 @@
+import type { DatabaseInterface } from '@happyvertical/sql';
+import { type LearnerRequest } from './learner-service.js';
+import { QuestionResponseService } from './question-response-service.js';
+import { type TutorAudience, type TutorContext } from './tutor-contracts.js';
+export type TutorContextRequest = LearnerRequest & {
+    audience: TutorAudience;
+    enrollmentId?: string;
+    lessonId?: string;
+    /** Focus one question of the lesson (a question revision id). */
+    questionRevisionId?: string;
+};
+/**
+ * Composes the bounded `TutorContext` for one learner. Pure data: no AI call,
+ * no prompt text. Every read uses this service's executor and the
+ * `education.tutor.read` decision of the host authorizer, with the same
+ * actor/tenant/relationship checks as `LearnerService`.
+ */
+export declare class TutorContextService extends QuestionResponseService {
+    protected createTransactionService(db: DatabaseInterface): this;
+    compose(request: TutorContextRequest): Promise<TutorContext>;
+    /** The released lesson revision and ordered question refs, or null if none. */
+    private releasedLesson;
+    private objectiveStatements;
+    /** Count and latest status only: no notes, intake ids or files. */
+    private submissionSummary;
+    /**
+     * Learner audience: the newest assessment revision a guardian explicitly
+     * released, its feedback text only (no score, concept labels or per-question
+     * detail). Guardian audience: the newest guardian-confirmed revision, else
+     * the newest one.
+     */
+    private releasedFeedback;
+}
+//# sourceMappingURL=tutor-context-service.d.ts.map

package/dist/tutor-context-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tutor-context-service.d.ts","sourceRoot":"","sources":["../src/tutor-context-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAG5D,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EACL,uBAAuB,EAExB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAYL,KAAK,aAAa,EAClB,KAAK,YAAY,EAElB,MAAM,sBAAsB,CAAC;AAI9B,MAAM,MAAM,mBAAmB,GAAG,cAAc,GAAG;IACjD,QAAQ,EAAE,aAAa,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC;AAEF;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,uBAAuB;cAC3C,wBAAwB,CAAC,EAAE,EAAE,iBAAiB,GAAG,IAAI;IAQlE,OAAO,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,YAAY,CAAC;IA0UlE,+EAA+E;YACjE,cAAc;YAwBd,mBAAmB;IA0BjC,mEAAmE;YACrD,iBAAiB;IAmB/B;;;;;OAKG;YACW,gBAAgB;CA4D/B"}

package/dist/tutor-contracts.d.ts

@@ -0,0 +1,123 @@
+import { LearnerValidationError } from './learner-service.js';
+export declare const TUTOR_AUDIENCES: readonly ["learner", "guardian"];
+export type TutorAudience = (typeof TUTOR_AUDIENCES)[number];
+export declare const TUTOR_SESSION_MODES: readonly ["chat", "voice"];
+export type TutorSessionMode = (typeof TUTOR_SESSION_MODES)[number];
+export declare const TUTOR_EXCHANGE_ROLES: readonly ["learner", "tutor", "system"];
+export type TutorExchangeRole = (typeof TUTOR_EXCHANGE_ROLES)[number];
+/** Host content/safety classification of one exchange; `none` is unclassified. */
+export declare const TUTOR_EXCHANGE_MARKERS: readonly ["none", "filtered", "redacted", "flagged"];
+export type TutorExchangeMarker = (typeof TUTOR_EXCHANGE_MARKERS)[number];
+/** Longest lesson body, in characters; longer text is cut and `truncated` set. */
+export declare const MAX_TUTOR_BODY_CHARS = 8000;
+/** Longest question prompt, subpart prompt or choice label, in characters. */
+export declare const MAX_TUTOR_PROMPT_CHARS = 2000;
+/** Longest answer key or rubric text (guardian audience), in characters. */
+export declare const MAX_TUTOR_KEY_CHARS = 2000;
+/** Longest released-feedback text, in characters. */
+export declare const MAX_TUTOR_FEEDBACK_CHARS = 2000;
+/** Longest title or objective statement, in characters. */
+export declare const MAX_TUTOR_TITLE_CHARS = 300;
+export declare const MAX_TUTOR_QUESTIONS = 30;
+export declare const MAX_TUTOR_CHOICES = 12;
+export declare const MAX_TUTOR_SUBPARTS = 12;
+export declare const MAX_TUTOR_OBJECTIVES = 10;
+/** Serialized size ceiling of a whole context; trailing questions drop first. */
+export declare const MAX_TUTOR_CONTEXT_CHARS = 48000;
+/** Longest exchange text, in characters. Over-cap or empty text is refused. */
+export declare const MAX_TUTOR_EXCHANGE_TEXT_CHARS = 4000;
+export declare const MAX_TUTOR_TOOL_SUMMARY_CHARS = 1000;
+export declare const DEFAULT_TUTOR_SESSION_PAGE = 20;
+export declare const MAX_TUTOR_SESSION_PAGE = 50;
+export declare const DEFAULT_TUTOR_EXCHANGE_PAGE = 50;
+export declare const MAX_TUTOR_EXCHANGE_PAGE = 200;
+export type TutorQuestionItem = Readonly<{
+    ordinal: number;
+    questionRevisionId: string;
+    prompt: string;
+    responseType: string;
+    choices: ReadonlyArray<{
+        id: string;
+        label: string;
+    }>;
+    subparts: ReadonlyArray<{
+        partKey: string;
+        prompt: string;
+    }>;
+    pointsPossible: number | null;
+    /** Guardian audience only: answer key as capped JSON text. */
+    answerKey?: string | null;
+    /** Guardian audience only: rubric as capped JSON text. */
+    rubric?: string | null;
+}>;
+/**
+ * Bounded, data-only view a host may turn into tutor prompts. For the learner
+ * audience it holds no answer key, rubric, guardian note, storage locator,
+ * asset id, other learner's data or grading internals; only
+ * `answerKeyAvailable` says that a key exists.
+ */
+export type TutorContext = Readonly<{
+    version: 1;
+    audience: TutorAudience;
+    learner: Readonly<{
+        id: string;
+        displayName: string;
+        level: number;
+    }>;
+    enrollment: Readonly<{
+        id: string;
+        courseId: string;
+        status: string;
+        lessonsPerWeek: number | null;
+    }> | null;
+    course: Readonly<{
+        id: string;
+        title: string;
+    }> | null;
+    section: Readonly<{
+        title: string;
+    }> | null;
+    lesson: Readonly<{
+        id: string;
+        title: string;
+        kind: string;
+        /** Learner-facing lesson text; empty when withheld or absent. */
+        body: string;
+        bodyWithheld: boolean;
+        estimatedMinutes: number;
+    }> | null;
+    objectives: ReadonlyArray<string>;
+    progress: Readonly<{
+        status: string;
+        completedAt: string | null;
+    }> | null;
+    questions: ReadonlyArray<TutorQuestionItem>;
+    /** The question the tutor is asked about, when one was requested. */
+    focusQuestionRevisionId: string | null;
+    submissions: Readonly<{
+        count: number;
+        latestStatus: string | null;
+    }>;
+    /** Latest explicitly released feedback text for the lesson, if any. */
+    feedback: Readonly<{
+        text: string;
+    }> | null;
+    answerKeyAvailable: boolean;
+    /** True when any text or list was cut to fit a bound. */
+    truncated: boolean;
+    /** Digest of this context; sessions store it instead of the text. */
+    contextHash: string;
+}>;
+export declare class TutorSessionClosedError extends LearnerValidationError {
+    constructor();
+}
+export declare class TutorRequestKeyConflictError extends LearnerValidationError {
+    constructor();
+}
+export declare class TutorConsentRequiredError extends LearnerValidationError {
+    constructor();
+}
+export declare class TutorExchangeError extends LearnerValidationError {
+    constructor(message: string);
+}
+//# sourceMappingURL=tutor-contracts.d.ts.map

package/dist/tutor-contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tutor-contracts.d.ts","sourceRoot":"","sources":["../src/tutor-contracts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,eAAO,MAAM,eAAe,kCAAmC,CAAC;AAChE,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAC7D,eAAO,MAAM,mBAAmB,4BAA6B,CAAC;AAC9D,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AACpE,eAAO,MAAM,oBAAoB,yCAA0C,CAAC;AAC5E,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AACtE,kFAAkF;AAClF,eAAO,MAAM,sBAAsB,sDAKzB,CAAC;AACX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAG1E,kFAAkF;AAClF,eAAO,MAAM,oBAAoB,OAAO,CAAC;AACzC,8EAA8E;AAC9E,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAC3C,4EAA4E;AAC5E,eAAO,MAAM,mBAAmB,OAAO,CAAC;AACxC,qDAAqD;AACrD,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAC7C,2DAA2D;AAC3D,eAAO,MAAM,qBAAqB,MAAM,CAAC;AACzC,eAAO,MAAM,mBAAmB,KAAK,CAAC;AACtC,eAAO,MAAM,iBAAiB,KAAK,CAAC;AACpC,eAAO,MAAM,kBAAkB,KAAK,CAAC;AACrC,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,iFAAiF;AACjF,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAG9C,+EAA+E;AAC/E,eAAO,MAAM,6BAA6B,OAAO,CAAC;AAClD,eAAO,MAAM,4BAA4B,OAAO,CAAC;AACjD,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAC7C,eAAO,MAAM,sBAAsB,KAAK,CAAC;AACzC,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAC9C,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAE3C,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,aAAa,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtD,QAAQ,EAAE,aAAa,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC;IAClC,OAAO,EAAE,CAAC,CAAC;IACX,QAAQ,EAAE,aAAa,CAAC;IACxB,OAAO,EAAE,QAAQ,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtE,UAAU,EAAE,QAAQ,CAAC;QACnB,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;KAC/B,CAAC,GAAG,IAAI,CAAC;IACV,MAAM,EAAE,QAAQ,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,IAAI,CAAC;IACvD,OAAO,EAAE,QAAQ,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,IAAI,CAAC;IAC5C,MAAM,EAAE,QAAQ,CAAC;QACf,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,iEAAiE;QACjE,IAAI,EAAE,MAAM,CAAC;QACb,YAAY,EAAE,OAAO,CAAC;QACtB,gBAAgB,EAAE,MAAM,CAAC;KAC1B,CAAC,GAAG,IAAI,CAAC;IACV,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAClC,QAAQ,EAAE,QAAQ,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;KAC5B,CAAC,GAAG,IAAI,CAAC;IACV,SAAS,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAC;IAC5C,qEAAqE;IACrE,uBAAuB,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,WAAW,EAAE,QAAQ,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IACtE,uEAAuE;IACvE,QAAQ,EAAE,QAAQ,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,IAAI,CAAC;IAC5C,kBAAkB,EAAE,OAAO,CAAC;IAC5B,yDAAyD;IACzD,SAAS,EAAE,OAAO,CAAC;IACnB,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC,CAAC;AAEH,qBAAa,uBAAwB,SAAQ,sBAAsB;;CAKlE;AACD,qBAAa,4BAA6B,SAAQ,sBAAsB;;CAKvE;AACD,qBAAa,yBAA0B,SAAQ,sBAAsB;;CAKpE;AACD,qBAAa,kBAAmB,SAAQ,sBAAsB;gBAChD,OAAO,EAAE,MAAM;CAI5B"}

package/dist/tutor-models.d.ts

@@ -0,0 +1,77 @@
+import { SmrtCollection, SmrtObject, type SmrtSaveOptions } from '@happyvertical/smrt-core';
+import { type TutorAudience, type TutorExchangeMarker, type TutorExchangeRole, type TutorSessionMode } from './tutor-contracts.js';
+/**
+ * Append-only record that a tutor session was opened for one learner. It holds
+ * identifiers and a context digest only: never context text, and never answer
+ * material. "Open" is the absence of a `TutorSessionClosure`.
+ */
+export declare class TutorSession extends SmrtObject {
+    tenantId: string;
+    learnerId: string;
+    enrollmentId: string | null;
+    lessonId: string | null;
+    audience: TutorAudience;
+    mode: TutorSessionMode;
+    /** Voice consent the host recorded for this learner before a voice session. */
+    voiceConsent: boolean;
+    openedByUserId: string;
+    /** Idempotency key for `open`, unique per learner. */
+    requestKey: string;
+    /** Digest of the request, so a changed replay is refused. */
+    requestDigest: string;
+    /** Digest of the `TutorContext` given to the tutor; never the context itself. */
+    contextHash: string | null;
+    openedAt: Date;
+    constructor(options?: Record<string, unknown>);
+    delete(): Promise<void>;
+    save(options?: SmrtSaveOptions): Promise<this>;
+}
+export declare class TutorSessionCollection extends SmrtCollection<TutorSession> {
+    static readonly _itemClass: typeof TutorSession;
+}
+/**
+ * Append-only close record, at most one per session. A session is closed once
+ * this row exists; the session row itself is never rewritten.
+ */
+export declare class TutorSessionClosure extends SmrtObject {
+    tenantId: string;
+    sessionId: string;
+    learnerId: string;
+    actorUserId: string;
+    closedAt: Date;
+    constructor(options?: Record<string, unknown>);
+    delete(): Promise<void>;
+    save(options?: SmrtSaveOptions): Promise<this>;
+}
+export declare class TutorSessionClosureCollection extends SmrtCollection<TutorSessionClosure> {
+    static readonly _itemClass: typeof TutorSessionClosure;
+}
+/** Append-only message in a tutor session, ordered by `sequence` from 1. */
+export declare class TutorExchange extends SmrtObject {
+    tenantId: string;
+    sessionId: string;
+    learnerId: string;
+    sequence: number;
+    role: TutorExchangeRole;
+    text: string;
+    actorUserId: string;
+    /** Optional context reference: ids only. */
+    lessonId: string | null;
+    questionRevisionId: string | null;
+    /** Host content/safety classification of this text. */
+    marker: TutorExchangeMarker;
+    /** Short host-written summary of tool calls; never raw arguments. */
+    toolSummary: string;
+    inputTokens: number;
+    outputTokens: number;
+    requestKey: string;
+    requestDigest: string;
+    recordedAt: Date;
+    constructor(options?: Record<string, unknown>);
+    delete(): Promise<void>;
+    save(options?: SmrtSaveOptions): Promise<this>;
+}
+export declare class TutorExchangeCollection extends SmrtCollection<TutorExchange> {
+    static readonly _itemClass: typeof TutorExchange;
+}
+//# sourceMappingURL=tutor-models.d.ts.map

package/dist/tutor-models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tutor-models.d.ts","sourceRoot":"","sources":["../src/tutor-models.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,cAAc,EACd,UAAU,EACV,KAAK,eAAe,EAErB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAOL,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACtB,MAAM,sBAAsB,CAAC;AA4B9B;;;;GAIG;AACH,qBAMa,YAAa,SAAQ,UAAU;IAC9B,QAAQ,SAAM;IACiB,SAAS,SAAM;IACjB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAQ;IACnC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IACxE,QAAQ,EAAE,aAAa,CAAa;IACpC,IAAI,EAAE,gBAAgB,CAAU;IAChC,+EAA+E;IAC/E,YAAY,UAAS;IACrB,cAAc,SAAM;IACpB,sDAAsD;IACtD,UAAU,SAAM;IAChB,6DAA6D;IAC7D,aAAa,SAAM;IACnB,iFAAiF;IACxC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAQ;IAC3E,QAAQ,OAAc;gBACV,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;IAIlC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAGvB,IAAI,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;CAmC9D;AACD,qBAAa,sBAAuB,SAAQ,cAAc,CAAC,YAAY,CAAC;IACtE,MAAM,CAAC,QAAQ,CAAC,UAAU,sBAAgB;CAC3C;AAED;;;GAGG;AACH,qBAMa,mBAAoB,SAAQ,UAAU;IACrC,QAAQ,SAAM;IACsB,SAAS,SAAM;IACpB,SAAS,SAAM;IAC1D,WAAW,SAAM;IACjB,QAAQ,OAAc;gBACV,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;IAIlC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAGvB,IAAI,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;CAe9D;AACD,qBAAa,6BAA8B,SAAQ,cAAc,CAAC,mBAAmB,CAAC;IACpF,MAAM,CAAC,QAAQ,CAAC,UAAU,6BAAuB;CAClD;AAED,4EAA4E;AAC5E,qBAaa,aAAc,SAAQ,UAAU;IAC/B,QAAQ,SAAM;IACsB,SAAS,SAAM;IACpB,SAAS,SAAM;IAC1D,QAAQ,SAAK;IACb,IAAI,EAAE,iBAAiB,CAAa;IACX,IAAI,SAAM;IACnC,WAAW,SAAM;IACjB,4CAA4C;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAC/B,kBAAkB,EAAE,MAAM,GAAG,IAAI,CACnE;IACP,uDAAuD;IACvD,MAAM,EAAE,mBAAmB,CAAU;IACrC,qEAAqE;IAC5C,WAAW,SAAM;IAC1C,WAAW,SAAK;IAChB,YAAY,SAAK;IACjB,UAAU,SAAM;IAChB,aAAa,SAAM;IACnB,UAAU,OAAc;gBACZ,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;IAIlC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAGvB,IAAI,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;CAqC9D;AACD,qBAAa,uBAAwB,SAAQ,cAAc,CAAC,aAAa,CAAC;IACxE,MAAM,CAAC,QAAQ,CAAC,UAAU,uBAAiB;CAC5C"}

package/dist/tutor-session-service.d.ts

@@ -0,0 +1,115 @@
+import type { DatabaseInterface } from '@happyvertical/sql';
+import { type LearnerRequest, LearnerService } from './learner-service.js';
+import { type TutorAudience, type TutorExchangeMarker, type TutorExchangeRole, type TutorSessionMode } from './tutor-contracts.js';
+export type TutorExchangeView = Readonly<{
+    id: string;
+    sessionId: string;
+    sequence: number;
+    role: TutorExchangeRole;
+    text: string;
+    actorUserId: string;
+    lessonId: string | null;
+    questionRevisionId: string | null;
+    marker: TutorExchangeMarker;
+    toolSummary: string;
+    inputTokens: number;
+    outputTokens: number;
+    recordedAt: string;
+}>;
+export type TutorSessionView = Readonly<{
+    id: string;
+    learnerId: string;
+    enrollmentId: string | null;
+    lessonId: string | null;
+    audience: TutorAudience;
+    mode: TutorSessionMode;
+    voiceConsent: boolean;
+    openedByUserId: string;
+    /** Digest of the context the tutor was given; never the context itself. */
+    contextHash: string | null;
+    openedAt: string;
+    closedAt: string | null;
+}>;
+export type TutorSessionWithExchanges = TutorSessionView & Readonly<{
+    exchanges: ReadonlyArray<TutorExchangeView>;
+    /** True when more exchanges exist after the returned ones. */
+    exchangesTruncated: boolean;
+}>;
+export type OpenTutorSessionRequest = LearnerRequest & {
+    requestKey: string;
+    audience?: TutorAudience;
+    mode?: TutorSessionMode;
+    /** The host's recorded voice consent for this learner; required for voice. */
+    voiceConsent?: boolean;
+    enrollmentId?: string;
+    lessonId?: string;
+    /** `TutorContext.contextHash` of the context given to the tutor. */
+    contextHash?: string;
+};
+export type AppendTutorExchangeRequest = LearnerRequest & {
+    sessionId: string;
+    requestKey: string;
+    role: TutorExchangeRole;
+    text: string;
+    lessonId?: string;
+    questionRevisionId?: string;
+    marker?: TutorExchangeMarker;
+    toolSummary?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+};
+export type ListTutorSessionsRequest = LearnerRequest & {
+    enrollmentId?: string;
+    lessonId?: string;
+    /** Restrict to one session and page its exchanges with `afterSequence`. */
+    sessionId?: string;
+    afterSequence?: number;
+    limit?: number;
+    cursor?: string;
+    exchangeLimit?: number;
+};
+/**
+ * Append-only tutor transcripts. No AI call happens here: the host owns the
+ * model call and the spend ceiling, and records what was said. Actions:
+ * `education.tutor.exchange` (open, append, close) and `education.tutor.read`
+ * (listForLearner), decided by the host authorizer with the same actor, tenant
+ * and guardian-relationship checks as `LearnerService`.
+ */
+export declare class TutorSessionService extends LearnerService {
+    protected createTransactionService(db: DatabaseInterface): this;
+    private requireTables;
+    private session;
+    private closure;
+    /** Opens a session; a replay of the same request key returns the same one. */
+    open(request: OpenTutorSessionRequest): Promise<TutorSessionView & {
+        changed: boolean;
+    }>;
+    /**
+     * Appends one exchange. `role: 'learner'` is accepted only from the learner
+     * themself; a guardian may append `tutor` or `system` rows. Text must be
+     * non-empty and at most `MAX_TUTOR_EXCHANGE_TEXT_CHARS`. A replay of a
+     * request key returns the stored row; an append to a closed session is
+     * refused with `TutorSessionClosedError`.
+     */
+    append(request: AppendTutorExchangeRequest): Promise<TutorExchangeView & {
+        changed: boolean;
+    }>;
+    /** Closes a session by appending a closure; closing twice is a no-op. */
+    close(request: LearnerRequest & {
+        sessionId: string;
+    }): Promise<TutorSessionView & {
+        changed: boolean;
+    }>;
+    /**
+     * The learner's own sessions, newest first, with a bounded number of
+     * exchanges each (first by sequence). `limit` (default 20, max 50) and
+     * `cursor` page sessions; `exchangeLimit` (default 50, max 200) bounds
+     * exchanges, and `sessionId` + `afterSequence` page one session's exchanges.
+     * Guardians read through the host's `education.tutor.read` decision.
+     */
+    listForLearner(request: ListTutorSessionsRequest): Promise<{
+        sessions: TutorSessionWithExchanges[];
+        nextCursor: string | null;
+    }>;
+}
+//# sourceMappingURL=tutor-session-service.d.ts.map

package/dist/tutor-session-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tutor-session-service.d.ts","sourceRoot":"","sources":["../src/tutor-session-service.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-education",
-  "version": "0.57.47",
+  "version": "0.57.49",
   "smrtJsdoc": "strict",
   "description": "Tenant-aware learning catalog models and authorized catalog access for SMRT",
   "type": "module",
@@ -25,18 +25,18 @@
     }
   },
   "dependencies": {
-    "@happyvertical/smrt-assets": "0.57.47",
-    "@happyvertical/smrt-core": "0.57.47",
-    "@happyvertical/smrt-profiles": "0.57.47",
-    "@happyvertical/smrt-tenancy": "0.57.47",
-    "@happyvertical/smrt-users": "0.57.47",
+    "@happyvertical/smrt-assets": "0.57.49",
+    "@happyvertical/smrt-core": "0.57.49",
+    "@happyvertical/smrt-profiles": "0.57.49",
+    "@happyvertical/smrt-tenancy": "0.57.49",
+    "@happyvertical/smrt-users": "0.57.49",
     "@happyvertical/files": "^0.111.3",
     "@happyvertical/sql": "^0.111.3",
     "pdf-lib": "1.17.1",
-    "@happyvertical/smrt-ingestion": "0.57.47"
+    "@happyvertical/smrt-ingestion": "0.57.49"
   },
   "devDependencies": {
-    "@happyvertical/smrt-vitest": "0.57.47",
+    "@happyvertical/smrt-vitest": "0.57.49",
     "@types/node": "24.13.6",
     "typescript": "6.0.3",
     "vite": "8.1.6",