@rimori/client 2.5.55-next.0 → 2.5.56-next.0

package/dist/controller/AccomplishmentController.d.ts

@@ -1,9 +1,18 @@
 import { EventBusHandler, EventBusMessage } from '../fromRimori/EventBus';
 export type AccomplishmentMessage = EventBusMessage<MicroAccomplishmentPayload>;
 export declare const skillCategories: readonly ["reading", "listening", "speaking", "writing", "learning", "community"];
+/**
+ * The single declaration of the accomplishment skill categories. Previously re-typed by hand in
+ * `useAccomplishmentChecker` (rimori-main) and `UseExerciseHook` (react-client), which could
+ * drift apart silently.
+ *
+ * Distinct from rimori-main's `SkillCategory` in `types/skill_progress.ts`: that one names the
+ * columns of the `skill_progress` table (…, 'understanding', 'grammar') and is a different set.
+ */
+export type SkillCategory = (typeof skillCategories)[number];
 interface BaseAccomplishmentPayload {
     type: 'micro' | 'macro';
-    skillCategory: (typeof skillCategories)[number];
+    skillCategory: SkillCategory;
     accomplishmentKeyword: string;
     description: string;
     meta?: {

package/dist/controller/AccomplishmentController.js

@@ -35,12 +35,6 @@ export class AccomplishmentController {
         if (!['micro', 'macro'].includes(payload.type)) {
             throw new Error('Invalid accomplishment type ' + payload.type);
         }
-        // disabled detection temporarelly to determine how long exercises normally are
-        //durationMinutes is required
-        // if (payload.type === 'macro' && payload.durationMinutes < 4) {
-        //   console.warn('The duration must be at least 4 minutes');
-        //   return false;
-        // }
         //errorRatio is required
         if (payload.type === 'macro' && (payload.errorRatio < 0 || payload.errorRatio > 1)) {
             throw new Error('The error ratio must be between 0 and 1');

package/dist/fromRimori/ActionParams.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The one validator for "does this value set satisfy an action's declared parameter schema?".
+ *
+ * There used to be a copy of this rule per caller — the dashboard's CreateExerciseDialog gated
+ * its Next button on it, and RouterHandler threw on it before navigating — which let them
+ * disagree about what counts as a provided value. They now share this.
+ *
+ * Note this is a *pre-flight* check, not a trust boundary: it runs in the browser, so anything
+ * server-side must re-validate rather than trust a caller that says it already did.
+ */
+/** The subset of `ToolParameter` this check needs — kept structural so any superset fits. */
+export interface ActionParameterSchema {
+    optional?: boolean;
+}
+/**
+ * Names of the required (non-`optional`) parameters that `values` does not provide.
+ *
+ * "Not provided" is `undefined`, `null` or the empty string only — `false` and `0` are real
+ * answers for a boolean/number parameter and must not read as missing.
+ */
+export declare function findMissingActionParams(parameters: Record<string, ActionParameterSchema>, values: Record<string, unknown>): string[];
+/** True when every required parameter of the action is provided. */
+export declare function hasRequiredActionParams(parameters: Record<string, ActionParameterSchema>, values: Record<string, unknown>): boolean;

package/dist/fromRimori/ActionParams.js

@@ -0,0 +1,28 @@
+/**
+ * The one validator for "does this value set satisfy an action's declared parameter schema?".
+ *
+ * There used to be a copy of this rule per caller — the dashboard's CreateExerciseDialog gated
+ * its Next button on it, and RouterHandler threw on it before navigating — which let them
+ * disagree about what counts as a provided value. They now share this.
+ *
+ * Note this is a *pre-flight* check, not a trust boundary: it runs in the browser, so anything
+ * server-side must re-validate rather than trust a caller that says it already did.
+ */
+/**
+ * Names of the required (non-`optional`) parameters that `values` does not provide.
+ *
+ * "Not provided" is `undefined`, `null` or the empty string only — `false` and `0` are real
+ * answers for a boolean/number parameter and must not read as missing.
+ */
+export function findMissingActionParams(parameters, values) {
+    return Object.keys(parameters).filter((key) => {
+        if (parameters[key]?.optional)
+            return false;
+        const value = values[key];
+        return value === undefined || value === null || value === '';
+    });
+}
+/** True when every required parameter of the action is provided. */
+export function hasRequiredActionParams(parameters, values) {
+    return findMissingActionParams(parameters, values).length === 0;
+}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from './fromRimori/EventBus';
 export * from './plugin/RimoriClient';
 export * from './fromRimori/PluginTypes';
+export * from './fromRimori/ActionParams';
 export * from './plugin/StandaloneClient';
 export * from './cli/types/DatabaseTypes';
 export * from './cli/types/PromptTypes';
@@ -12,15 +13,16 @@ export { setupWorker } from './worker/WorkerSetup';
 export type { EventBusMessage } from './fromRimori/EventBus';
 export { AudioController } from './controller/AudioController';
 export { voiceDebug } from './plugin/VoiceDebugStore';
-export type { Exercise } from './plugin/module/ExerciseModule';
+export type { ExerciseRow, CreateExerciseRowParams, CompleteExerciseParams, EvidenceKind } from './plugin/module/ExerciseModule';
 export { Translator } from './controller/TranslationController';
-export type { TriggerAction } from './plugin/module/ExerciseModule';
-export type { Message, ToolInvocation } from './plugin/module/AIModule';
+export type { Message, ToolInvocation, WireMessage, ToolCallContentPart, ToolResultContentPart, ToolResultOutput } from './plugin/module/AIModule';
+export { toModelMessages } from './plugin/module/AIModule';
 export type { Theme, ApplicationMode } from './plugin/module/PluginModule';
 export type { UserInfo, Language, UserRole, SubscriptionTier, ExplicitUndefined, BasePluginSettings, Buddy } from './plugin/module/PluginModule';
 export { TIER_ORDER, ROLE_ORDER } from './plugin/module/PluginModule';
 export type { SharedContent, BasicSharedContent, ContentStatus } from './plugin/module/SharedContentController';
-export type { MacroAccomplishmentPayload, MicroAccomplishmentPayload } from './controller/AccomplishmentController';
+export type { MacroAccomplishmentPayload, MicroAccomplishmentPayload, AccomplishmentPayload, SkillCategory, } from './controller/AccomplishmentController';
+export { skillCategories } from './controller/AccomplishmentController';
 export { StorageModule } from './plugin/module/StorageModule';
 export { AssetsModule, type AssetKind } from './plugin/module/AssetsModule';
 export type { PublicityLevel } from './plugin/module/DbModule';

package/dist/index.js

@@ -2,6 +2,7 @@
 export * from './fromRimori/EventBus';
 export * from './plugin/RimoriClient';
 export * from './fromRimori/PluginTypes';
+export * from './fromRimori/ActionParams';
 export * from './plugin/StandaloneClient';
 export * from './cli/types/DatabaseTypes';
 export * from './cli/types/PromptTypes';
@@ -12,6 +13,8 @@ export { setupWorker } from './worker/WorkerSetup';
 export { AudioController } from './controller/AudioController';
 export { voiceDebug } from './plugin/VoiceDebugStore';
 export { Translator } from './controller/TranslationController';
+export { toModelMessages } from './plugin/module/AIModule';
 export { TIER_ORDER, ROLE_ORDER } from './plugin/module/PluginModule';
+export { skillCategories } from './controller/AccomplishmentController';
 export { StorageModule } from './plugin/module/StorageModule';
 export { AssetsModule } from './plugin/module/AssetsModule';

package/dist/modules.d.ts

@@ -1,5 +1,8 @@
 export * from './fromRimori/EventBus';
 export * from './plugin/module/AIModule';
 export * from './fromRimori/PluginTypes';
+export * from './fromRimori/ActionParams';
+export type { MacroAccomplishmentPayload, MicroAccomplishmentPayload, AccomplishmentPayload, SkillCategory, } from './controller/AccomplishmentController';
+export { skillCategories } from './controller/AccomplishmentController';
 export * from './cli/types/DatabaseTypes';
 export * from './plugin/TTS/MessageSender';

package/dist/modules.js

@@ -2,5 +2,7 @@
 export * from './fromRimori/EventBus';
 export * from './plugin/module/AIModule';
 export * from './fromRimori/PluginTypes';
+export * from './fromRimori/ActionParams';
+export { skillCategories } from './controller/AccomplishmentController';
 export * from './cli/types/DatabaseTypes';
 export * from './plugin/TTS/MessageSender';

package/dist/plugin/RimoriClient.d.ts

@@ -31,6 +31,14 @@ export declare class RimoriClient {
      */
     static createWithInfo(info: RimoriInfo, applicationMode?: ApplicationMode): RimoriClient;
     static getInstance(pluginId?: string): Promise<RimoriClient>;
+    /**
+     * Resolves once no plugin operation that still has to emit on the event bus is in flight.
+     *
+     * The host (PluginRenderer) awaits this before tearing the plugin's event bus down, so a
+     * fire-and-forget mutation started just before the user navigated away still gets its event
+     * delivered. Extend this if another module ever gains an emit that happens *after* an await.
+     */
+    whenIdle(): Promise<void>;
     navigation: {
         toDashboard: () => void;
     };

package/dist/plugin/RimoriClient.js

@@ -89,6 +89,16 @@ export class RimoriClient {
         }
         return RimoriClient.instance;
     }
+    /**
+     * Resolves once no plugin operation that still has to emit on the event bus is in flight.
+     *
+     * The host (PluginRenderer) awaits this before tearing the plugin's event bus down, so a
+     * fire-and-forget mutation started just before the user navigated away still gets its event
+     * delivered. Extend this if another module ever gains an emit that happens *after* an await.
+     */
+    async whenIdle() {
+        await this.exercise.whenIdle();
+    }
     navigation = {
         toDashboard: () => {
             this.event.emit('global.navigation.triggerToDashboard');

package/dist/plugin/module/AIModule.d.ts

@@ -35,6 +35,12 @@ export interface ToolInvocation {
     toolCallId: string;
     toolName: string;
     args: Record<string, string>;
+    /**
+     * The tool's own return value, recorded locally right after `execute()` resolves (see the
+     * `tool:` branch in `streamObject`). Optional so a call whose execution failed still
+     * round-trips as a call without a result rather than being dropped entirely.
+     */
+    result?: unknown;
 }
 export interface Message {
     id?: string;
@@ -43,6 +49,57 @@ export interface Message {
     toolCalls?: ToolInvocation[];
 }
 export type OnLLMResponse = (id: string, response: string, finished: boolean, toolInvocations?: ToolInvocation[]) => void;
+/** Wire-format tool-call content part of an `assistant` message — mirrors the AI SDK's `ToolCallPart`. */
+export interface ToolCallContentPart {
+    type: 'tool-call';
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+}
+/** Wire-format tagged output envelope the AI SDK requires on a tool result (bare values are rejected). */
+export type ToolResultOutput = {
+    type: 'text';
+    value: string;
+} | {
+    type: 'json';
+    value: unknown;
+};
+/** Wire-format tool-result content part of a `tool` message — mirrors the AI SDK's `ToolResultPart`. */
+export interface ToolResultContentPart {
+    type: 'tool-result';
+    toolCallId: string;
+    toolName: string;
+    output: ToolResultOutput;
+}
+/**
+ * A message as it travels over the wire to `/ai/llm` — this is what the backend's `MessageDto`
+ * accepts. Distinct from `Message` (the client-side chat-history shape) because a single
+ * `Message` with N tool calls expands into 2N+1 wire messages (see `toModelMessages`).
+ */
+export interface WireMessage {
+    id?: string;
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    content: string | ToolCallContentPart[] | ToolResultContentPart[];
+}
+/**
+ * Expands client-side chat history into the flat wire format the backend/AI SDK expects.
+ * Every tool call on an assistant message becomes its own `assistant(tool-call)` +
+ * `tool(tool-result)` pair, in call order, immediately adjacent — providers reject a `tool`
+ * message that doesn't immediately follow the assistant message that issued its call, and the
+ * client has no reliable way to know the backend's original step boundaries, so 1:1 pairing is
+ * the only ordering that is always valid (the only fidelity loss is that calls that were
+ * genuinely parallel within one step replay as sequential ones, which is semantically
+ * irrelevant to the model).
+ *
+ * An assistant row with neither visible text nor tool calls is dropped — the AI SDK's message
+ * schema rejects it (this is the crash `UseChatHook.ts`'s `append` already filters out at the
+ * state layer; this is the second, defense-in-depth place, since `BuddyAssistant` does not
+ * filter its own state).
+ *
+ * Exported for direct unit testing — this is pure and the cheapest place to cover the wire
+ * format's edge cases (see packages/rimori-client/test).
+ */
+export declare function toModelMessages(history: Message[]): WireMessage[];
 /**
  * Controller for AI-related operations.
  * Provides access to text generation, voice synthesis, and object generation.

package/dist/plugin/module/AIModule.js

@@ -1,3 +1,84 @@
+/**
+ * How many of the most recent tool-calling turns keep their full tool-result payload when
+ * serialized. Older turns keep the call (so the model still "remembers that it looked") but
+ * have their result replaced with a short placeholder — tool results are the fastest-growing
+ * part of context (see ai.service.ts's per-step inputTokens log), and after this fix they
+ * accumulate for the whole conversation instead of being forgotten every turn, so trimming is
+ * load-bearing, not a nicety.
+ */
+const FULL_FIDELITY_TOOL_RESULT_TURNS = 3;
+function toToolResultOutput(result, keepFull) {
+    if (!keepFull) {
+        return {
+            type: 'text',
+            value: '(result omitted to save context — this tool was already called earlier in the conversation)',
+        };
+    }
+    if (result === undefined)
+        return { type: 'text', value: '(no result recorded)' };
+    if (typeof result === 'string')
+        return { type: 'text', value: result };
+    return { type: 'json', value: result };
+}
+/**
+ * Expands client-side chat history into the flat wire format the backend/AI SDK expects.
+ * Every tool call on an assistant message becomes its own `assistant(tool-call)` +
+ * `tool(tool-result)` pair, in call order, immediately adjacent — providers reject a `tool`
+ * message that doesn't immediately follow the assistant message that issued its call, and the
+ * client has no reliable way to know the backend's original step boundaries, so 1:1 pairing is
+ * the only ordering that is always valid (the only fidelity loss is that calls that were
+ * genuinely parallel within one step replay as sequential ones, which is semantically
+ * irrelevant to the model).
+ *
+ * An assistant row with neither visible text nor tool calls is dropped — the AI SDK's message
+ * schema rejects it (this is the crash `UseChatHook.ts`'s `append` already filters out at the
+ * state layer; this is the second, defense-in-depth place, since `BuddyAssistant` does not
+ * filter its own state).
+ *
+ * Exported for direct unit testing — this is pure and the cheapest place to cover the wire
+ * format's edge cases (see packages/rimori-client/test).
+ */
+export function toModelMessages(history) {
+    const toolCallRowIndices = history
+        .map((m, i) => (m.toolCalls && m.toolCalls.length > 0 ? i : -1))
+        .filter((i) => i !== -1);
+    const fullFidelityIndices = new Set(toolCallRowIndices.slice(-FULL_FIDELITY_TOOL_RESULT_TURNS));
+    const out = [];
+    history.forEach((message, index) => {
+        const hasToolCalls = !!message.toolCalls && message.toolCalls.length > 0;
+        const hasText = typeof message.content === 'string' && message.content.length > 0;
+        if (!hasToolCalls) {
+            // A user row is always kept even if somehow empty; a text-less, tool-call-less
+            // assistant/system row is exactly the schema-invalid shape called out above.
+            if (!hasText && message.role !== 'user')
+                return;
+            out.push({ role: message.role, content: message.content });
+            return;
+        }
+        const keepFullResults = fullFidelityIndices.has(index);
+        for (const call of message.toolCalls) {
+            out.push({
+                role: 'assistant',
+                content: [{ type: 'tool-call', toolCallId: call.toolCallId, toolName: call.toolName, input: call.args }],
+            });
+            out.push({
+                role: 'tool',
+                content: [
+                    {
+                        type: 'tool-result',
+                        toolCallId: call.toolCallId,
+                        toolName: call.toolName,
+                        output: toToolResultOutput(call.result, keepFullResults),
+                    },
+                ],
+            });
+        }
+        if (hasText) {
+            out.push({ role: 'assistant', content: message.content });
+        }
+    });
+    return out;
+}
 /**
  * Controller for AI-related operations.
  * Provides access to text generation, voice synthesis, and object generation.
@@ -55,14 +136,14 @@ export class AIModule {
      */
     async getText(params) {
         const { messages, tools, cache = false, prompt, variables } = params;
-        const { result } = await this.streamObject({
+        const { data } = await this.streamObject({
             cache,
             tools,
             messages,
             prompt,
             variables,
         });
-        return result;
+        return data.result;
     }
     /**
      * Stream text generation from messages using AI.
@@ -76,7 +157,7 @@ export class AIModule {
     async getStreamedText(params) {
         const { messages, onMessage, tools, cache = false, prompt, variables, } = params;
         const messageId = Math.random().toString(36).substring(3);
-        const { result } = await this.streamObject({
+        const { data, toolExchanges } = await this.streamObject({
             cache,
             tools,
             messages,
@@ -84,8 +165,10 @@ export class AIModule {
             variables,
             onResult: ({ result }) => onMessage(messageId, result, false),
         });
-        onMessage(messageId, result, true);
-        return result;
+        // Only the final callback carries the turn's tool exchanges — intermediate `finished:
+        // false` calls fire on every partial chunk and should not churn the caller's tool state.
+        onMessage(messageId, data.result, true, toolExchanges.length > 0 ? toolExchanges : undefined);
+        return data.result;
     }
     /**
      * Generate voice audio from text using AI.
@@ -184,13 +267,14 @@ export class AIModule {
      */
     async getObject(params) {
         const { cache = false, tools = [], prompt, variables } = params;
-        return await this.streamObject({
+        const { data } = await this.streamObject({
             messages: [],
             cache,
             tools,
             prompt,
             variables,
         });
+        return data;
     }
     /**
      * Generate a streamed structured object from a request using AI.
@@ -205,7 +289,7 @@ export class AIModule {
      */
     async getStreamedObject(params) {
         const { onResult, cache = false, tools = [], prompt, variables, settledOnly = false } = params;
-        return await this.streamObject({
+        const { data } = await this.streamObject({
             messages: [],
             onResult,
             cache,
@@ -214,13 +298,21 @@ export class AIModule {
             variables,
             settledOnly,
         });
+        return data;
     }
     async streamObject(params) {
         const { messages, onResult = () => null, cache = false, tools = [], prompt, variables, settledOnly = false, } = params;
-        const chatMessages = messages.map((message, index) => ({
+        // toModelMessages expands any tool calls in history into their own assistant/tool wire
+        // messages first (C9: ids are positional, so they must be assigned after expansion).
+        const chatMessages = toModelMessages(messages).map((message, index) => ({
             ...message,
             id: `${index + 1}`,
         }));
+        // Records each tool call this request makes together with the result the client computed
+        // for it, so the caller (getStreamedText → BuddyAssistant/useChat) can persist the pair into
+        // chat history — this is the only place that ever sees both halves together (see the `tool:`
+        // branch below).
+        const exchanges = [];
         const payload = {
             cache,
             tools,
@@ -284,7 +376,7 @@ export class AIModule {
                 isLoading = false;
                 onResult(currentObject, false);
                 logFinalResult();
-                return currentObject;
+                return { data: currentObject, toolExchanges: exchanges };
             }
             //the check needs to be behind readerDone because in closed connections the value is undefined
             if (!value)
@@ -333,7 +425,7 @@ export class AIModule {
                     isLoading = false;
                     onResult(currentObject, false);
                     logFinalResult();
-                    return currentObject;
+                    return { data: currentObject, toolExchanges: exchanges };
                 }
                 if (command === 'data:') {
                     currentObject = JSON.parse(dataStr);
@@ -344,6 +436,7 @@ export class AIModule {
                     const tool = tools.find((tool) => tool.name === toolName);
                     if (tool && tool.execute) {
                         const result = await tool.execute(args);
+                        exchanges.push({ toolCallId, toolName, args, result });
                         // Send the result to the backend
                         await this.sendToolResult(toolCallId, result);
                     }
@@ -366,12 +459,23 @@ export class AIModule {
                 }
             }
         }
-        return currentObject;
+        return { data: currentObject, toolExchanges: exchanges };
     }
     async sendToolResult(toolCallId, result) {
+        // A tool returning nothing used to be sent to the backend as the literal '[DONE]' sentinel,
+        // which the backend treats as an explicit "stop the conversation" signal and throws —
+        // turning a small tool bug into a dead chat. No tool in this codebase ever intentionally
+        // returns undefined to end the conversation, so instead send a non-empty error string the
+        // model can react to (e.g. apologize and retry) rather than silently killing the turn.
+        if (result === undefined || result === null || result === '') {
+            console.error(`Tool call ${toolCallId} returned an empty result — sending a fallback error instead.`);
+        }
+        const safeResult = result === undefined || result === null || result === ''
+            ? 'The tool call failed to produce a result. Tell the user something went wrong and suggest they try again.'
+            : result;
         await this.controller.fetchBackend('/ai/llm/tool_result', {
             method: 'POST',
-            body: JSON.stringify({ toolCallId, result: result ?? '[DONE]' }),
+            body: JSON.stringify({ toolCallId, result: safeResult }),
         });
     }
 }

package/dist/plugin/module/ExerciseModule.d.ts

@@ -1,55 +1,101 @@
 import { SupabaseClient } from '../CommunicationHandler';
 import { RimoriCommunicationHandler, RimoriInfo } from '../CommunicationHandler';
 import { EventModule } from './EventModule';
-export type TriggerAction = {
-    action_key: string;
-} & Record<string, string | number | boolean>;
-export interface CreateExerciseParams {
-    plugin_id: string;
-    start_date: string;
-    end_date: string;
-    trigger_action: TriggerAction;
-    name: string;
-    description: string;
-    estimated_duration: number;
-    achievement_topic: string;
-}
-export interface Exercise {
+/**
+ * A row of `public.exercises` (see planning/exercise-system-simplification.md). Flat
+ * `plugin_id`/`action_key`/`params` replace the old `attributes` jsonb blob, and `status`
+ * replaces the achievement_event_log anti-join.
+ */
+export interface ExerciseRow {
     id: string;
+    user_id: string;
     plugin_id: string;
+    action_key: string;
+    params: Record<string, string | number | boolean | undefined>;
+    name: string | null;
+    description: string | null;
     start_date: string;
     end_date: string;
-    attributes: TriggerAction;
-    achievement_topic: string;
-    name: string;
-    description: string;
-    estimated_duration: number;
-    created_at?: string;
-    updated_at?: string;
+    status: 'pending' | 'completed' | 'expired';
+    completed_at: string | null;
+    created_at: string;
+}
+/** Body of `POST /exercises` — no achievement_topic, no skill category, no reward fields. */
+export interface CreateExerciseRowParams {
+    pluginId: string;
+    actionKey: string;
+    params?: Record<string, string | number | boolean | undefined>;
+    name?: string;
+    description?: string;
+    /** ISO 8601 */
+    startDate: string;
+    /** ISO 8601 */
+    endDate: string;
 }
 /**
- * Controller for exercise-related operations.
- * Provides access to weekly exercises and exercise management.
+ * The kind of evidence an exercise page produces. Constant per page — never calculated from
+ * the run's outcome — because it describes what the interaction *is* (recognising a word vs.
+ * producing one), not how well the user did.
+ */
+export type EvidenceKind = 'recognition' | 'comprehension' | 'controlled' | 'production_written' | 'production_spoken';
+/** Body of `POST /exercises/:id/complete` — measurements only, the id identifies the row. */
+export interface CompleteExerciseParams {
+    errorRatio?: number;
+    durationMinutes?: number;
+    meta?: Record<string, unknown>;
+    /** The kind of evidence this result rests on. Required — a constant per exercise page. */
+    evidenceKind: EvidenceKind;
+    /** How many cards/questions/sentences the result rests on. */
+    itemCount?: number;
+    /** Named part-scores (0..1) where the page computes several and would otherwise discard them. */
+    components?: Record<string, number>;
+}
+/** Supabase-style result, per the repo's error-handling convention. */
+type Result<T> = {
+    data: T;
+    error?: undefined;
+} | {
+    data?: undefined;
+    error: Error;
+};
+/**
+ * Controller for exercise-related operations: reading the current week's open exercises,
+ * creating them, and marking them complete.
  */
 export declare class ExerciseModule {
     private supabase;
     private communicationHandler;
     private eventModule;
+    /**
+     * Mutations that still have to emit on the event bus after their backend round trip.
+     * The host tears the plugin's event bus down on unmount, so it drains this set first
+     * (see `whenIdle`) — otherwise a completion whose response lands after the user
+     * navigated away emits into a cleared bus and the dashboard never refetches.
+     */
+    private pending;
     constructor(supabase: SupabaseClient, communicationHandler: RimoriCommunicationHandler, _info: RimoriInfo, eventModule: EventModule);
     /**
-     * Fetches weekly exercises from the weekly_exercises view.
-     * Shows exercises for the current week that haven't expired.
-     * @returns Array of exercise objects.
+     * Registers a mutation as in-flight for the duration of its promise. Every tracked method
+     * emits its bus event as the last statement before resolving, so a caller awaiting
+     * `whenIdle()` is guaranteed to run *after* the emit, not merely after the HTTP response.
+     */
+    private track;
+    /**
+     * Resolves once no mutation that still has to emit on the event bus is in flight.
+     * Loops because a tracked mutation may itself start another one while draining.
+     */
+    whenIdle(): Promise<void>;
+    /**
+     * Reads the current user's open exercises from the `weekly_exercises` view
+     * (`status = 'pending'`, inside this week's date window).
      */
-    view(): Promise<Exercise[]>;
+    view(): Promise<Result<ExerciseRow[]>>;
     /**
-     * Creates one or more exercises via the backend API.
-     * Multiple exercises are sent in a single bulk request to ensure atomicity —
-     * either all succeed or none are inserted.
-     * @param params Exercise creation parameters (single or array).
-     * @returns Created exercise objects.
+     * Creates one exercise. Single-row only — callers that create a batch fan out, so a partial
+     * failure is possible (the old achievements-backed bulk endpoint was all-or-nothing).
      */
-    add(params: CreateExerciseParams | CreateExerciseParams[]): Promise<Exercise[]>;
+    add(params: CreateExerciseRowParams): Promise<Result<ExerciseRow>>;
+    private addInternal;
     /**
      * Requests a new exercise session token from rimori-main.
      * Use this for self-initiated exercises (user navigated to plugin via navbar and clicked Start).
@@ -67,12 +113,15 @@ export declare class ExerciseModule {
         knowledgeId?: string;
     }): Promise<void>;
     /**
-     * Deletes an exercise via the backend API.
-     * @param id The exercise ID to delete.
-     * @returns Success status.
+     * Marks an exercise completed. The measurements are reported on the completion but are not
+     * stored on the exercise row — they travel on the backend's `exercise.completed` event.
      */
-    delete(id: string): Promise<{
-        success: boolean;
-        message: string;
-    }>;
+    complete(exerciseId: string, params: CompleteExerciseParams): Promise<Result<ExerciseRow>>;
+    private completeInternal;
+    /** Deletes an exercise. */
+    delete(id: string): Promise<Result<{
+        success: true;
+    }>>;
+    private deleteInternal;
 }
+export {};

package/dist/plugin/module/ExerciseModule.js

@@ -1,48 +1,73 @@
 /**
- * Controller for exercise-related operations.
- * Provides access to weekly exercises and exercise management.
+ * Controller for exercise-related operations: reading the current week's open exercises,
+ * creating them, and marking them complete.
  */
 export class ExerciseModule {
     supabase;
     communicationHandler;
     eventModule;
+    /**
+     * Mutations that still have to emit on the event bus after their backend round trip.
+     * The host tears the plugin's event bus down on unmount, so it drains this set first
+     * (see `whenIdle`) — otherwise a completion whose response lands after the user
+     * navigated away emits into a cleared bus and the dashboard never refetches.
+     */
+    pending = new Set();
     constructor(supabase, communicationHandler, _info, eventModule) {
         this.supabase = supabase;
         this.communicationHandler = communicationHandler;
         this.eventModule = eventModule;
     }
     /**
-     * Fetches weekly exercises from the weekly_exercises view.
-     * Shows exercises for the current week that haven't expired.
-     * @returns Array of exercise objects.
+     * Registers a mutation as in-flight for the duration of its promise. Every tracked method
+     * emits its bus event as the last statement before resolving, so a caller awaiting
+     * `whenIdle()` is guaranteed to run *after* the emit, not merely after the HTTP response.
+     */
+    track(operation) {
+        this.pending.add(operation);
+        // Swallow here only to keep the bookkeeping alive — the original promise is returned
+        // untouched, so the caller still sees any rejection.
+        void operation.catch(() => { }).finally(() => this.pending.delete(operation));
+        return operation;
+    }
+    /**
+     * Resolves once no mutation that still has to emit on the event bus is in flight.
+     * Loops because a tracked mutation may itself start another one while draining.
+     */
+    async whenIdle() {
+        while (this.pending.size > 0) {
+            await Promise.allSettled([...this.pending]);
+        }
+    }
+    /**
+     * Reads the current user's open exercises from the `weekly_exercises` view
+     * (`status = 'pending'`, inside this week's date window).
      */
     async view() {
         const { data, error } = await this.supabase.schema('public').from('weekly_exercises').select('*');
         if (error) {
-            throw new Error(`Failed to fetch weekly exercises: ${error.message}`);
+            return { error: new Error(`Failed to fetch weekly exercises: ${error.message}`) };
         }
-        return data || [];
+        return { data: (data ?? []) };
     }
     /**
-     * Creates one or more exercises via the backend API.
-     * Multiple exercises are sent in a single bulk request to ensure atomicity —
-     * either all succeed or none are inserted.
-     * @param params Exercise creation parameters (single or array).
-     * @returns Created exercise objects.
+     * Creates one exercise. Single-row only — callers that create a batch fan out, so a partial
+     * failure is possible (the old achievements-backed bulk endpoint was all-or-nothing).
      */
     async add(params) {
-        const exercises = Array.isArray(params) ? params : [params];
+        return this.track(this.addInternal(params));
+    }
+    async addInternal(params) {
         const response = await this.communicationHandler.fetchBackend('/exercises', {
             method: 'POST',
-            body: JSON.stringify({ exercises }),
+            body: JSON.stringify(params),
         });
         if (!response.ok) {
-            const errorText = await response.text();
-            throw new Error(`Failed to create exercises: ${errorText}`);
+            return { error: new Error(`Failed to create exercise: ${await response.text()}`) };
         }
         const data = await response.json();
         this.eventModule.emit('global.exercises.triggerChange');
-        return data;
+        return { data };
     }
     /**
      * Requests a new exercise session token from rimori-main.
@@ -73,19 +98,36 @@ export class ExerciseModule {
         });
     }
     /**
-     * Deletes an exercise via the backend API.
-     * @param id The exercise ID to delete.
-     * @returns Success status.
+     * Marks an exercise completed. The measurements are reported on the completion but are not
+     * stored on the exercise row — they travel on the backend's `exercise.completed` event.
      */
+    async complete(exerciseId, params) {
+        return this.track(this.completeInternal(exerciseId, params));
+    }
+    async completeInternal(exerciseId, params) {
+        const response = await this.communicationHandler.fetchBackend(`/exercises/${exerciseId}/complete`, {
+            method: 'POST',
+            body: JSON.stringify(params),
+        });
+        if (!response.ok) {
+            return { error: new Error(`Failed to complete exercise: ${await response.text()}`) };
+        }
+        const data = await response.json();
+        this.eventModule.emit('global.exercises.triggerChange');
+        return { data };
+    }
+    /** Deletes an exercise. */
     async delete(id) {
+        return this.track(this.deleteInternal(id));
+    }
+    async deleteInternal(id) {
         const response = await this.communicationHandler.fetchBackend(`/exercises/${id}`, {
             method: 'DELETE',
         });
         if (!response.ok) {
-            const errorText = await response.text();
-            throw new Error(`Failed to delete exercise: ${errorText}`);
+            return { error: new Error(`Failed to delete exercise: ${await response.text()}`) };
         }
         this.eventModule.emit('global.exercises.triggerChange');
-        return await response.json();
+        return { data: { success: true } };
     }
 }

package/dist/plugin/module/PluginModule.d.ts

@@ -212,4 +212,12 @@ export interface UserInfo {
      * Undefined otherwise. Plugins decide how to use this on a per-feature basis.
      */
     dialect?: string;
+    /**
+     * True only while this render was triggered by a shared-exercise link (`/s/:id`) whose
+     * visitor's own tier doesn't clear the plugin's gate. UI-only fast-path signal — see
+     * `useTierGate` and the `shared_link_id` reserved key on `MainPanelAction`. The backend
+     * independently re-verifies the exercise session's shared_link_id before allowing the
+     * actual AI call, so this flag grants no access on its own.
+     */
+    via_shared_link?: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rimori/client",
-  "version": "2.5.55-next.0",
+  "version": "2.5.56-next.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "repository": {