om-memory-system 4.31.1 → 4.32.0

package/dist/importer/import-turn-outputs.js

@@ -84,5 +84,8 @@ export function importSkillTurnOutput(options, report) {
             return;
         // handleFinishedTurn logs a failure as skill-record-failed, so one bad turn never stops the run.
         await handleFinishedTurn(unit, { memories: false, skills: true }, { recordSkillTurn: async (turn) => count(await output(turn, current)) });
+        // `skills.db` writes finish without giving the event loop a turn. In the
+        // web app, a long run would otherwise hold back every request, progress included.
+        await new Promise((resolve) => setImmediate(resolve));
     };
 }

package/dist/services/ai/providers/base-provider.d.ts

@@ -39,6 +39,21 @@ export declare function toolCallFailureReason(result: ToolCallResult, lengthStop
  * conversation content, so it is replaced; validator messages name fields only.
  */
 export declare function describeValidationError(error: unknown): string;
+/**
+ * Where a JSON `SyntaxError` stopped, from Node's "at position N" text, or
+ * undefined when the runtime gives none. A position near the end of the
+ * arguments means a cut-off reply; one far before it means bad escaping.
+ */
+export declare function jsonErrorPosition(error: unknown): number | undefined;
+/** Log fields for a failed tool reply: no reply text, only codes and a position. */
+export declare function validationLogFields(error: unknown, stopReason: string | undefined): {
+    error: string;
+    errorType: string;
+    stopReason: string | null;
+    jsonErrorAt: number | null;
+};
+/** The error a failed tool reply returns. It says when the reply was cut off. */
+export declare function validationFailureMessage(error: unknown, stopReason: string | undefined): string;
 export declare function applySafeExtraParams(requestBody: Record<string, any>, extraParams: Record<string, unknown>): void;
 export declare abstract class BaseAIProvider {
     protected config: ProviderConfig;

package/dist/services/ai/providers/base-provider.js

@@ -29,6 +29,32 @@ export function describeValidationError(error) {
         return error.message;
     return "unknown validation error";
 }
+/**
+ * Where a JSON `SyntaxError` stopped, from Node's "at position N" text, or
+ * undefined when the runtime gives none. A position near the end of the
+ * arguments means a cut-off reply; one far before it means bad escaping.
+ */
+export function jsonErrorPosition(error) {
+    if (!(error instanceof SyntaxError))
+        return undefined;
+    const match = /at position (\d+)/.exec(error.message);
+    return match ? Number(match[1]) : undefined;
+}
+/** Log fields for a failed tool reply: no reply text, only codes and a position. */
+export function validationLogFields(error, stopReason) {
+    return {
+        error: describeValidationError(error),
+        errorType: error instanceof Error ? error.constructor.name : typeof error,
+        // "length" means the reply hit the output limit and was cut off.
+        stopReason: stopReason ?? null,
+        jsonErrorAt: jsonErrorPosition(error) ?? null,
+    };
+}
+/** The error a failed tool reply returns. It says when the reply was cut off. */
+export function validationFailureMessage(error, stopReason) {
+    const cutOff = stopReason === "length" ? " (the reply was cut off)" : "";
+    return `Validation failed: ${describeValidationError(error)}${cutOff}`;
+}
 const PROTECTED_KEYS = new Set([
     "model",
     "messages",

package/dist/services/ai/providers/openai-chat-completion.js

@@ -1,4 +1,4 @@
-import { BaseAIProvider, applySafeExtraParams, describeValidationError, isTransportError, } from "./base-provider.js";
+import { BaseAIProvider, applySafeExtraParams, validationFailureMessage, validationLogFields, isTransportError, } from "./base-provider.js";
 import { log } from "../../logger.js";
 import { UserProfileValidator } from "../validators/user-profile-validator.js";
 import { parseRetryAfter } from "../../../core/capture-retry-policy.js";
@@ -338,16 +338,13 @@ export class OpenAIChatCompletionProvider extends BaseAIProvider {
                             }
                             catch (validationError) {
                                 log("OpenAI tool response validation failed", {
-                                    error: describeValidationError(validationError),
-                                    errorType: validationError instanceof Error
-                                        ? validationError.constructor.name
-                                        : typeof validationError,
+                                    ...validationLogFields(validationError, stopReason),
                                     toolName: toolSchema.function.name,
                                     iteration: iterations,
                                     // Log only the size: the arguments are the model's reply.
                                     argumentsChars: toolCall.function.arguments.length,
                                 }, "error");
-                                const errorMessage = `Validation failed: ${describeValidationError(validationError)}`;
+                                const errorMessage = validationFailureMessage(validationError, stopReason);
                                 lastErrorMessage = errorMessage;
                                 await this.addToolResponse(session.id, messages, toolCallId, JSON.stringify({ success: false, error: errorMessage }));
                                 return {

package/dist/services/skill-learning/activity-range.d.ts

@@ -0,0 +1,46 @@
+export declare const ACTIVITY_DEFAULT_DAYS = 30;
+export declare const ACTIVITY_MAX_DAYS = 90;
+export declare const ACTIVITY_BUCKETS: readonly ["day", "month", "year"];
+export type ActivityBucket = (typeof ACTIVITY_BUCKETS)[number];
+/** Which periods to count: the last N days, one calendar month, one year, or every year. */
+export type ActivityQuery = {
+    bucket: "day";
+    days: number;
+} | {
+    bucket: "day";
+    month: string;
+} | {
+    bucket: "month";
+    year: number;
+} | {
+    bucket: "year";
+};
+export interface ActivityWindow {
+    /** First instant counted, UTC milliseconds. */
+    start: number;
+    /** First instant after the window. */
+    end: number;
+    /** One key per bar, oldest first: `YYYY-MM-DD`, `YYYY-MM` or `YYYY`. */
+    keys: string[];
+}
+/** The SQL that turns a use time into its bucket key. */
+export declare const BUCKET_SQL: Record<ActivityBucket, string>;
+export declare const utcYear: (now: number) => number;
+/**
+ * The window for a query. `firstYear` is the year of the earliest recorded
+ * use; the year bucket starts there and always reaches the year of `now`.
+ */
+export declare function activityWindow(query: ActivityQuery, now: number, firstYear: number | null): ActivityWindow;
+export declare const ACTIVITY_DEFAULT_TOP = 8;
+export declare const ACTIVITY_MAX_TOP = 100;
+/** How many of the most used skills to return: `top`, 1 to 100, default 8. */
+export declare const topParam: (url: URL) => number;
+/**
+ * The query from `bucket`, `days`, `month` and `year`. Numbers are clamped
+ * like every other Skills route number. An unknown bucket or a month that is
+ * not `YYYY-MM` from 1970 on gives an error, like an unknown `order`. With
+ * the day bucket, `month` wins over `days`.
+ */
+export declare function parseActivityQuery(url: URL, now: number): ActivityQuery | {
+    error: string;
+};

package/dist/services/skill-learning/activity-range.js

@@ -0,0 +1,83 @@
+import { intParam } from "./query-params.js";
+/*
+ * The time window of the Skills page activity charts: which UTC periods the
+ * chart shows, and how the route reads them from the query. Pure, so the
+ * window maths is tested without a database.
+ */
+const DAY_MS = 86_400_000;
+export const ACTIVITY_DEFAULT_DAYS = 30;
+export const ACTIVITY_MAX_DAYS = 90;
+export const ACTIVITY_BUCKETS = ["day", "month", "year"];
+/** Date.UTC reads a year below 100 as 1900 and up, so the earliest year is 1970. */
+const MIN_YEAR = 1970;
+const MAX_YEAR = 9999;
+/** The SQL that turns a use time into its bucket key. */
+export const BUCKET_SQL = {
+    day: `date(u.created_at / 1000, 'unixepoch')`,
+    month: `strftime('%Y-%m', u.created_at / 1000, 'unixepoch')`,
+    year: `strftime('%Y', u.created_at / 1000, 'unixepoch')`,
+};
+const pad = (value) => String(value).padStart(2, "0");
+const dayKey = (ms) => new Date(ms).toISOString().slice(0, 10);
+export const utcYear = (now) => new Date(now).getUTCFullYear();
+/**
+ * The window for a query. `firstYear` is the year of the earliest recorded
+ * use; the year bucket starts there and always reaches the year of `now`.
+ */
+export function activityWindow(query, now, firstYear) {
+    if (query.bucket === "year") {
+        const last = utcYear(now);
+        const first = Math.min(firstYear ?? last, last);
+        const keys = Array.from({ length: last - first + 1 }, (_, i) => String(first + i));
+        return { start: Date.UTC(first, 0, 1), end: Date.UTC(last + 1, 0, 1), keys };
+    }
+    if (query.bucket === "month") {
+        const keys = Array.from({ length: 12 }, (_, i) => `${query.year}-${pad(i + 1)}`);
+        return { start: Date.UTC(query.year, 0, 1), end: Date.UTC(query.year + 1, 0, 1), keys };
+    }
+    if ("month" in query) {
+        const [year, month] = query.month.split("-").map(Number);
+        const start = Date.UTC(year, month - 1, 1);
+        const end = Date.UTC(year, month, 1);
+        const keys = Array.from({ length: (end - start) / DAY_MS }, (_, i) => dayKey(start + i * DAY_MS));
+        return { start, end, keys };
+    }
+    const today = Math.floor(now / DAY_MS) * DAY_MS;
+    const start = today - (query.days - 1) * DAY_MS;
+    const keys = Array.from({ length: query.days }, (_, i) => dayKey(start + i * DAY_MS));
+    return { start, end: today + DAY_MS, keys };
+}
+export const ACTIVITY_DEFAULT_TOP = 8;
+export const ACTIVITY_MAX_TOP = 100;
+/** How many of the most used skills to return: `top`, 1 to 100, default 8. */
+export const topParam = (url) => intParam(url, "top", 1, ACTIVITY_MAX_TOP, ACTIVITY_DEFAULT_TOP);
+const MONTH = /^(\d{4})-(0[1-9]|1[0-2])$/;
+/**
+ * The query from `bucket`, `days`, `month` and `year`. Numbers are clamped
+ * like every other Skills route number. An unknown bucket or a month that is
+ * not `YYYY-MM` from 1970 on gives an error, like an unknown `order`. With
+ * the day bucket, `month` wins over `days`.
+ */
+export function parseActivityQuery(url, now) {
+    const bucket = url.searchParams.get("bucket")?.trim() || "day";
+    if (!ACTIVITY_BUCKETS.includes(bucket)) {
+        return { error: `bucket must be one of: ${ACTIVITY_BUCKETS.join(", ")}` };
+    }
+    if (bucket === "year")
+        return { bucket };
+    if (bucket === "month") {
+        return { bucket, year: intParam(url, "year", MIN_YEAR, MAX_YEAR, utcYear(now)) };
+    }
+    const month = url.searchParams.get("month")?.trim();
+    if (month) {
+        const match = MONTH.exec(month);
+        if (!match || Number(match[1]) < MIN_YEAR) {
+            return { error: `month must be YYYY-MM, from ${MIN_YEAR}-01` };
+        }
+        return { bucket: "day", month };
+    }
+    return {
+        bucket: "day",
+        days: intParam(url, "days", 1, ACTIVITY_MAX_DAYS, ACTIVITY_DEFAULT_DAYS),
+    };
+}

package/dist/services/skill-learning/activity.d.ts

@@ -0,0 +1,61 @@
+import { type ActivityBucket, type ActivityQuery } from "./activity-range.js";
+import type { SkillIndex } from "./skill-index.js";
+import type { SkillStore } from "./store.js";
+/** The per-skill chart always shows this many days. */
+export declare const SKILL_DAILY_DAYS = 30;
+export { ACTIVITY_DEFAULT_DAYS, ACTIVITY_MAX_DAYS } from "./activity-range.js";
+export interface DailyUses {
+    /** UTC day, `YYYY-MM-DD`. */
+    day: string;
+    /** Turns that used the skill that day. */
+    uses: number;
+    /** Of those turns, the ones with a failed tool call after the skill was used. */
+    failed: number;
+}
+/** Uses in one UTC period: a day `YYYY-MM-DD`, a month `YYYY-MM` or a year `YYYY`. */
+export interface PeriodUses {
+    key: string;
+    uses: number;
+    failed: number;
+}
+export interface SkillActivity {
+    bucket: ActivityBucket;
+    /** One entry per period of the window, oldest first, zero-filled. */
+    series: PeriodUses[];
+    /** The day series as `{ day }` rows, as before. Empty for months and years. */
+    days: DailyUses[];
+    topSkills: {
+        name: string;
+        path: string | null;
+        uses: number;
+        failed: number;
+    }[];
+    /** Distinct skills used in the window, so a list of the top skills knows when to stop. */
+    topTotal: number;
+    totals: {
+        uses: number;
+        failed: number;
+        activeSkills: number;
+    };
+    /** Months with a use, and years with a use plus this year, newest first. */
+    available: {
+        months: string[];
+        years: number[];
+    };
+}
+/**
+ * One skill's uses and failed turns for each of the last 30 UTC days, oldest
+ * first, with zero days included. A missing `skills.db` gives all zeros and
+ * stays missing.
+ */
+export declare function skillDaily(store: SkillStore, index: SkillIndex, skill: {
+    name: string;
+    path: string | null;
+}, now: number): Promise<DailyUses[]>;
+/**
+ * Uses and failed turns per UTC period across all skills, the `top` most used
+ * skills in the same window (8 by default), and the window totals. Counts a use like the
+ * ranking does, so a turn that used two skills counts once for each. A number
+ * asks for that many days ending today, as before.
+ */
+export declare function skillActivity(store: SkillStore, index: SkillIndex, now: number, request: ActivityQuery | number, top?: number): Promise<SkillActivity>;

package/dist/services/skill-learning/activity.js

@@ -0,0 +1,88 @@
+import { ACTIVITY_DEFAULT_TOP, BUCKET_SQL, activityWindow, utcYear, } from "./activity-range.js";
+import { USES_CTES } from "./ranking.js";
+/** The per-skill chart always shows this many days. */
+export const SKILL_DAILY_DAYS = 30;
+export { ACTIVITY_DEFAULT_DAYS, ACTIVITY_MAX_DAYS } from "./activity-range.js";
+function fillKeys(keys, rows) {
+    const byKey = new Map(rows.map((r) => [String(r.key), r]));
+    return keys.map((key) => {
+        const row = byKey.get(key);
+        return { key, uses: Number(row?.uses ?? 0), failed: Number(row?.failed ?? 0) };
+    });
+}
+const asDays = (series) => series.map(({ key, uses, failed }) => ({ day: key, uses, failed }));
+const entriesJson = (index) => JSON.stringify(index.entries.map((e) => ({ name: e.name, path: e.path })));
+/**
+ * One skill's uses and failed turns for each of the last 30 UTC days, oldest
+ * first, with zero days included. A missing `skills.db` gives all zeros and
+ * stays missing.
+ */
+export async function skillDaily(store, index, skill, now) {
+    const window = activityWindow({ bucket: "day", days: SKILL_DAILY_DAYS }, now, null);
+    const db = await store.existingDb();
+    if (!db)
+        return asDays(fillKeys(window.keys, []));
+    const rows = await db.all(`WITH ${USES_CTES}
+     SELECT ${BUCKET_SQL.day} AS key, COUNT(*) AS uses, SUM(u.failed) AS failed
+     FROM uses u
+     WHERE u.name = ? AND ${skill.path ? "u.path = ?" : "u.path IS NULL"}
+     GROUP BY key`, [entriesJson(index), window.start, skill.name, ...(skill.path ? [skill.path] : [])]);
+    return asDays(fillKeys(window.keys, rows));
+}
+/** Every month with a use, newest first, and those years plus the year of `now`. */
+async function availablePeriods(db, json, now) {
+    const rows = db
+        ? await db.all(`WITH ${USES_CTES}
+         SELECT DISTINCT ${BUCKET_SQL.month} AS month FROM uses u ORDER BY month DESC`, [json, 0])
+        : [];
+    const months = rows.map((r) => String(r.month));
+    const years = [...new Set([utcYear(now), ...months.map((m) => Number(m.slice(0, 4)))])];
+    return { months, years: years.sort((a, b) => b - a) };
+}
+/**
+ * Uses and failed turns per UTC period across all skills, the `top` most used
+ * skills in the same window (8 by default), and the window totals. Counts a use like the
+ * ranking does, so a turn that used two skills counts once for each. A number
+ * asks for that many days ending today, as before.
+ */
+export async function skillActivity(store, index, now, request, top = ACTIVITY_DEFAULT_TOP) {
+    const query = typeof request === "number" ? { bucket: "day", days: request } : request;
+    const db = await store.existingDb();
+    const json = entriesJson(index);
+    const available = await availablePeriods(db, json, now);
+    const oldest = available.months.at(-1);
+    const window = activityWindow(query, now, oldest ? Number(oldest.slice(0, 4)) : null);
+    // The CTEs take the index and the window start; the end bounds the window.
+    const args = [json, window.start, window.end];
+    const keyRows = db
+        ? await db.all(`WITH ${USES_CTES}
+         SELECT ${BUCKET_SQL[query.bucket]} AS key, COUNT(*) AS uses, SUM(u.failed) AS failed
+         FROM uses u WHERE u.created_at < ? GROUP BY key`, args)
+        : [];
+    const skillRows = db
+        ? await db.all(`WITH ${USES_CTES}
+         SELECT u.name, u.path, COUNT(*) AS uses, SUM(u.failed) AS failed
+         FROM uses u WHERE u.created_at < ? GROUP BY u.name, u.path
+         ORDER BY uses DESC, u.name ASC, u.path ASC`, args)
+        : [];
+    const series = fillKeys(window.keys, keyRows);
+    const skills = skillRows.map((r) => ({
+        name: String(r.name),
+        path: r.path == null ? null : String(r.path),
+        uses: Number(r.uses),
+        failed: Number(r.failed),
+    }));
+    return {
+        bucket: query.bucket,
+        series,
+        days: query.bucket === "day" ? asDays(series) : [],
+        topSkills: skills.slice(0, top),
+        topTotal: skills.length,
+        totals: {
+            uses: series.reduce((n, d) => n + d.uses, 0),
+            failed: series.reduce((n, d) => n + d.failed, 0),
+            activeSkills: skills.length,
+        },
+        available,
+    };
+}

package/dist/services/skill-learning/apply.d.ts

@@ -42,9 +42,12 @@ export declare function hashSkillContent(content: string | Buffer): string;
  * previous content before the write. Expected outcomes return a result code.
  */
 export declare function applyProposal(id: string, by: SkillAppliedBy, deps: ApplyDeps): Promise<ApplyResult>;
+/** True when `undoProposal` would accept this proposal now. Writes nothing. */
+export declare function canUndoProposal(id: string, deps: ApplyDeps): Promise<boolean>;
 /**
  * Restores the content saved before the last apply, or deletes the file the
  * apply created. Only when the file still matches what OMMS wrote; otherwise
- * refuses and returns the saved content.
+ * refuses and returns the saved content. So an older change is refused once a
+ * later change has rewritten the file, until that later change is undone.
  */
 export declare function undoProposal(id: string, deps: ApplyDeps): Promise<UndoResult>;

package/dist/services/skill-learning/apply.js

@@ -187,13 +187,8 @@ function removeEmptyFolder(folder, roots) {
         // The folder is gone or not empty; leave it.
     }
 }
-/**
- * Restores the content saved before the last apply, or deletes the file the
- * apply created. Only when the file still matches what OMMS wrote; otherwise
- * refuses and returns the saved content.
- */
-export async function undoProposal(id, deps) {
-    const now = deps.now ?? Date.now;
+/** Every check undo makes before it writes. Reads only; changes nothing. */
+async function planUndo(id, deps) {
     const { store } = deps;
     if (store.isReadOnly()) {
         return {
@@ -223,6 +218,24 @@ export async function undoProposal(id, deps) {
             savedContent: version.previousContent,
         };
     }
+    return { ok: true, proposal, version, real, folders };
+}
+/** True when `undoProposal` would accept this proposal now. Writes nothing. */
+export async function canUndoProposal(id, deps) {
+    return (await planUndo(id, deps)).ok;
+}
+/**
+ * Restores the content saved before the last apply, or deletes the file the
+ * apply created. Only when the file still matches what OMMS wrote; otherwise
+ * refuses and returns the saved content. So an older change is refused once a
+ * later change has rewritten the file, until that later change is undone.
+ */
+export async function undoProposal(id, deps) {
+    const now = deps.now ?? Date.now;
+    const plan = await planUndo(id, deps);
+    if (!plan.ok)
+        return plan;
+    const { proposal, version, real, folders } = plan;
     try {
         if (version.previousContent === null) {
             unlinkSync(real);
@@ -237,7 +250,7 @@ export async function undoProposal(id, deps) {
     }
     clearSkillIndexCache();
     const undoneAt = now();
-    await updateProposalState(store, id, "undone", undoneAt);
+    await updateProposalState(deps.store, id, "undone", undoneAt);
     return {
         ok: true,
         code: "undone",

package/dist/services/skill-learning/drafting.js

@@ -90,7 +90,8 @@ function nowOf(deps) {
 }
 const FAILURE_TEXT = {
     "not-configured": "The external API is not set up. Set it up in the External API card.",
-    "invalid-reply": "The model reply was not valid, so nothing was saved",
+    // One reply in two came back as broken JSON in a live check, so a retry usually works.
+    "invalid-reply": "The model reply was not valid, so nothing was saved. Try again.",
     timeout: "The model did not reply in time",
 };
 /** Log one metadata record, start the skill draft wait and return the failure. */

package/dist/services/skill-learning/history.d.ts

@@ -0,0 +1,48 @@
+import { type ApplyDeps } from "./apply.js";
+import { type SkillProposal } from "./proposal-store.js";
+export type SkillHistoryKind = "created" | "applied" | "rejected" | "undone" | "stale";
+export interface SkillHistoryEntry {
+    /** `<proposal id>:created` or `<proposal id>:<state>`. */
+    id: string;
+    proposalId: string;
+    kind: SkillHistoryKind;
+    /** Epoch ms: the proposal's creation time, or the time it reached this state. */
+    at: number;
+    summary: string;
+    appliedBy: string | null;
+    /** The saved version of an applied change; null for any other kind. */
+    versionId: string | null;
+    /** True only when `undoProposal` would accept this change now. */
+    canUndo: boolean;
+    /** Applied changes to the same skill saved after this one. */
+    laterAppliedCount: number;
+    added: number;
+    removed: number;
+}
+/** Added and removed line counts of a unified-style line diff. Hunk headers are skipped. */
+export declare function countDiffLines(diff: string | null): {
+    added: number;
+    removed: number;
+};
+/**
+ * The change history of one skill, newest first: a `created` entry for each
+ * proposal and a second entry once it was applied, rejected, undone or found
+ * stale. `canUndo` runs the same checks as undo, so it is false for an older
+ * change once a later change rewrote the file, and for a file edited by hand.
+ * No proposals, or no `skills.db`, give an empty history.
+ */
+export declare function skillHistory(deps: ApplyDeps, skill: {
+    path?: string;
+    name?: string;
+}, limit: number, offset: number): Promise<{
+    total: number;
+    entries: SkillHistoryEntry[];
+}>;
+/**
+ * Each proposal with `canUndo`: true only for an applied proposal that undo
+ * would accept now, so false once a later change rewrote the file. Reads one
+ * saved version and one file hash per applied proposal, and nothing for the rest.
+ */
+export declare function withCanUndo(deps: ApplyDeps, proposals: readonly SkillProposal[]): Promise<(SkillProposal & {
+    canUndo: boolean;
+})[]>;

package/dist/services/skill-learning/history.js

@@ -0,0 +1,95 @@
+import { canUndoProposal } from "./apply.js";
+import { listProposals } from "./proposal-store.js";
+/** Added and removed line counts of a unified-style line diff. Hunk headers are skipped. */
+export function countDiffLines(diff) {
+    let added = 0;
+    let removed = 0;
+    for (const line of (diff ?? "").split("\n")) {
+        if (line.startsWith("@@"))
+            continue;
+        if (line.startsWith("+"))
+            added++;
+        else if (line.startsWith("-"))
+            removed++;
+    }
+    return { added, removed };
+}
+/** The newest saved version id for each proposal id. */
+async function latestVersionIds(deps, ids) {
+    const db = await deps.store.existingDb();
+    const found = new Map();
+    if (!db || ids.length === 0)
+        return found;
+    const rows = await db.all(`SELECT proposal_id, MAX(id) AS id FROM skill_versions
+     WHERE proposal_id IN (SELECT value FROM json_each(?)) GROUP BY proposal_id`, [JSON.stringify(ids)]);
+    for (const row of rows)
+        found.set(String(row.proposal_id), Number(row.id));
+    return found;
+}
+function entriesOf(proposal, versions) {
+    const counts = countDiffLines(proposal.diff);
+    const base = { proposalId: proposal.id, summary: proposal.summary ?? "", ...counts };
+    const entries = [
+        {
+            ...base,
+            id: `${proposal.id}:created`,
+            kind: "created",
+            at: proposal.createdAt,
+            appliedBy: null,
+            versionId: null,
+        },
+    ];
+    if (proposal.state !== "pending") {
+        const version = versions.get(proposal.id);
+        const applied = proposal.state === "applied";
+        entries.push({
+            ...base,
+            id: `${proposal.id}:${proposal.state}`,
+            kind: proposal.state,
+            at: proposal.updatedAt,
+            appliedBy: applied ? proposal.appliedBy : null,
+            versionId: applied && version !== undefined ? String(version) : null,
+        });
+    }
+    return entries;
+}
+/**
+ * The change history of one skill, newest first: a `created` entry for each
+ * proposal and a second entry once it was applied, rejected, undone or found
+ * stale. `canUndo` runs the same checks as undo, so it is false for an older
+ * change once a later change rewrote the file, and for a file edited by hand.
+ * No proposals, or no `skills.db`, give an empty history.
+ */
+export async function skillHistory(deps, skill, limit, offset) {
+    // A name without a path is a skill outside the watched folders. Its proposals
+    // have no path, so a watched skill that shares the name stays out.
+    const proposals = skill.path
+        ? await listProposals(deps.store, { skillPath: skill.path })
+        : (await listProposals(deps.store, { skillName: skill.name })).filter((p) => !p.skillPath);
+    const versions = await latestVersionIds(deps, proposals.filter((p) => p.state === "applied").map((p) => p.id));
+    const all = proposals.flatMap((p) => entriesOf(p, versions));
+    // At the same time, the later step (applied, rejected) sorts above `created`.
+    all.sort((a, b) => b.at - a.at || +(b.kind !== "created") - +(a.kind !== "created"));
+    const appliedVersionIds = [...versions.values()];
+    const page = all.slice(offset, offset + limit);
+    const entries = await Promise.all(page.map(async (entry) => {
+        const version = entry.kind === "applied" ? Number(entry.versionId) : null;
+        return {
+            ...entry,
+            canUndo: version !== null && (await canUndoProposal(entry.proposalId, deps)),
+            laterAppliedCount: version === null ? 0 : appliedVersionIds.filter((id) => id > version).length,
+        };
+    }));
+    return { total: all.length, entries };
+}
+/**
+ * Each proposal with `canUndo`: true only for an applied proposal that undo
+ * would accept now, so false once a later change rewrote the file. Reads one
+ * saved version and one file hash per applied proposal, and nothing for the rest.
+ */
+export async function withCanUndo(deps, proposals) {
+    return Promise.all(proposals.map(async (p) => ({
+        ...p,
+        canUndo: p.state === "applied" && (await canUndoProposal(p.id, deps)),
+    })));
+}

package/dist/services/skill-learning/query-params.d.ts

@@ -0,0 +1,5 @@
+/**
+ * An integer query parameter, clamped into `min` to `max`. A missing, empty or
+ * non-numeric value gives `fallback`. A fraction is rounded down.
+ */
+export declare function intParam(url: URL, name: string, min: number, max: number, fallback: number): number;

package/dist/services/skill-learning/query-params.js

@@ -0,0 +1,13 @@
+/**
+ * An integer query parameter, clamped into `min` to `max`. A missing, empty or
+ * non-numeric value gives `fallback`. A fraction is rounded down.
+ */
+export function intParam(url, name, min, max, fallback) {
+    const raw = url.searchParams.get(name);
+    if (raw === null || raw.trim() === "")
+        return fallback;
+    const value = Number(raw);
+    if (!Number.isFinite(value))
+        return fallback;
+    return Math.min(max, Math.max(min, Math.floor(value)));
+}

package/dist/services/skill-learning/ranking.d.ts

@@ -25,6 +25,7 @@ export interface SkillRanking {
     /** 5 uses, attention of 0.3, and a failed turn since the skill's last proposal or review. */
     suggested: boolean;
 }
+export declare const USES_CTES = "\nidx AS (\n  SELECT json_extract(value, '$.name') AS name, json_extract(value, '$.path') AS path\n  FROM json_each(?)\n),\nresolved AS (\n  SELECT\n    su.turn_id,\n    su.skill_name AS name,\n    CASE\n      WHEN su.skill_path IS NOT NULL AND EXISTS (SELECT 1 FROM idx WHERE idx.path = su.skill_path)\n        THEN su.skill_path\n      WHEN su.skill_path IS NULL AND (SELECT COUNT(*) FROM idx WHERE idx.name = su.skill_name) = 1\n        THEN (SELECT idx.path FROM idx WHERE idx.name = su.skill_name)\n      ELSE NULL\n    END AS path,\n    t.created_at,\n    COALESCE(su.position, -1) AS position\n  FROM skill_uses su\n  JOIN turns t ON t.id = su.turn_id\n  WHERE t.created_at >= ?\n),\nfirst_use AS (\n  SELECT turn_id, name, path, created_at, MIN(position) AS position\n  FROM resolved\n  GROUP BY turn_id, name, path\n),\nuses AS (\n  SELECT\n    f.turn_id,\n    f.name,\n    f.path,\n    f.created_at,\n    EXISTS (\n      SELECT 1 FROM tool_calls tc\n      WHERE tc.turn_id = f.turn_id AND tc.outcome = 'error' AND tc.position > f.position\n    ) AS failed\n  FROM first_use f\n)";
 /** (failed + 1) / (uses + 2): a skill with little evidence stays near the middle. */
 export declare function attentionScore(failedTurns: number, uses: number): number;
 /**

package/dist/services/skill-learning/ranking.js

@@ -11,8 +11,11 @@ export const SKILL_ORDERS = ["uses", "attention"];
 // order is above the earliest use position in that turn. A NULL position (a
 // row from before the column) and -1 (a slash command) count every failure.
 // A review (a draft with no change, or an automatic review) counts as a proposal.
-const RANKING_SQL = `
-WITH idx AS (
+// The activity charts reuse these CTEs (idx, resolved, first_use, uses) so they
+// count a use and a failed turn the same way. Parameters: the index JSON, then
+// the earliest turn time.
+export const USES_CTES = `
+idx AS (
   SELECT json_extract(value, '$.name') AS name, json_extract(value, '$.path') AS path
   FROM json_each(?)
 ),
@@ -49,7 +52,9 @@ uses AS (
       WHERE tc.turn_id = f.turn_id AND tc.outcome = 'error' AND tc.position > f.position
     ) AS failed
   FROM first_use f
-),
+)`;
+const RANKING_SQL = `
+WITH ${USES_CTES},
 last_proposal AS (
   SELECT path, MAX(at) AS at FROM (
     SELECT skill_path AS path, created_at AS at FROM skill_proposals WHERE skill_path IS NOT NULL