om-memory-system 4.30.1 → 4.31.2

package/dist/services/skill-learning/auto-review.js

@@ -0,0 +1,132 @@
+import { randomUUID } from "node:crypto";
+import { skillDraftBackoff } from "../../core/profile-backoff.js";
+import { log } from "../logger.js";
+import { TableLease } from "../turso/table-lease.js";
+import { applyProposal } from "./apply.js";
+import { countSkillUses, skillRef } from "./draft-turns.js";
+import { draftImprovement } from "./drafting.js";
+import { setSkillReview } from "./proposal-store.js";
+/** A skill in automatic mode is reviewed after this many new uses... */
+export const AUTO_REVIEW_MIN_USES = 10;
+/** ...and at least this long after its last review. */
+export const AUTO_REVIEW_MIN_GAP_MS = 24 * 3_600_000;
+/** The web app checks for due skills this often. */
+export const AUTO_REVIEW_INTERVAL_MS = 10 * 60_000;
+export const SKILL_REVIEW_LEASE_TABLE = "skill_review_lease";
+/** The review run record in `skills.db`, shared by every process. */
+export function skillReviewLease(store, now) {
+    return new TableLease({ table: SKILL_REVIEW_LEASE_TABLE, connection: () => store.db(), now });
+}
+/** Automatic skills with 10 new uses and 24 hours since their last review. Reads only. */
+async function dueSkills(deps, now) {
+    const db = await deps.store.existingDb();
+    if (!db)
+        return [];
+    const rows = await db.all(`SELECT skill_path, last_review_at, uses_at_last_review FROM skill_settings
+     WHERE mode = 'automatic' ORDER BY skill_path`);
+    const due = [];
+    for (const row of rows) {
+        // A skill no watched folder holds now gets no draft.
+        const ref = skillRef(deps.index, String(row.skill_path));
+        if (!ref)
+            continue;
+        const last = row.last_review_at == null ? null : Number(row.last_review_at);
+        if (last !== null && now - last < AUTO_REVIEW_MIN_GAP_MS)
+            continue;
+        const uses = await countSkillUses(db, ref);
+        if (uses - Number(row.uses_at_last_review ?? 0) < AUTO_REVIEW_MIN_USES)
+            continue;
+        due.push({ path: ref.path, uses });
+    }
+    return due;
+}
+async function reviewSkill(deps, skill, now) {
+    const draft = await draftImprovement(skill.path, { ...deps, now });
+    // A failed draft is not a review, so the skill is tried again after the wait.
+    if (!draft.ok)
+        return draft.code;
+    let code = draft.code;
+    if (draft.code === "proposed") {
+        // A file changed since the draft makes the proposal stale and stays as it is.
+        const applied = await applyProposal(draft.proposal.id, "automatic", {
+            store: deps.store,
+            folders: deps.folders,
+            now,
+        });
+        code = applied.code;
+    }
+    await setSkillReview(deps.store, skill.path, now(), skill.uses);
+    return code;
+}
+/**
+ * One automatic review pass (design §6). Drafts and applies an improvement
+ * for each due skill in automatic mode. Starts no draft during the skill
+ * draft wait, and runs only while it holds the `skill_review_lease`, so one
+ * review runs at a time across processes.
+ */
+export async function runAutoReview(deps, now) {
+    const reviews = [];
+    const backoff = deps.backoff ?? skillDraftBackoff;
+    if (!deps.model.ready)
+        return { skipped: "not-configured", reviews };
+    if (!backoff.canRun(now))
+        return { skipped: "backoff", reviews };
+    const due = await dueSkills(deps, now);
+    if (due.length === 0)
+        return { reviews };
+    if (await deps.lease.isActive())
+        return { skipped: "busy", reviews };
+    const owner = randomUUID();
+    await deps.lease.take(owner);
+    try {
+        for (const skill of due) {
+            if (!backoff.canRun(now))
+                return { skipped: "backoff", reviews };
+            if ((await deps.lease.beginBatch(owner)) !== "ok")
+                return { skipped: "superseded", reviews };
+            try {
+                reviews.push({ skillPath: skill.path, code: await reviewSkill(deps, skill, () => now) });
+            }
+            finally {
+                await deps.lease.endBatch(owner);
+            }
+        }
+        return { reviews };
+    }
+    finally {
+        await deps.lease.release(owner);
+    }
+}
+/**
+ * Runs `runAutoReview` every 10 minutes. `makeDeps` returns null while skill
+ * learning is off, and the tick then does nothing. A tick never overlaps the
+ * one before it. The timer does not keep the process alive. Returns a stop
+ * function.
+ */
+export function startAutoReviewLoop(makeDeps, intervalMs = AUTO_REVIEW_INTERVAL_MS) {
+    let running = false;
+    const tick = async () => {
+        if (running)
+            return;
+        running = true;
+        try {
+            const deps = await makeDeps();
+            if (!deps)
+                return;
+            const report = await runAutoReview(deps, Date.now());
+            if (report.reviews.length > 0) {
+                log("Skill automatic review finished", { codes: report.reviews.map((r) => r.code) });
+            }
+        }
+        catch (error) {
+            // The name only: a message can hold a path or provider text.
+            log("Skill automatic review failed", { error: error?.name ?? "error" }, "error");
+        }
+        finally {
+            running = false;
+        }
+    };
+    const timer = setInterval(() => void tick(), intervalMs);
+    timer.unref?.();
+    return () => clearInterval(timer);
+}

package/dist/services/skill-learning/draft-turns.d.ts

@@ -0,0 +1,60 @@
+import type { TursoDb } from "../turso/turso-db.js";
+import type { SkillIndex } from "./skill-index.js";
+/** Design §6: the budgets for turn text sent to the external API model. */
+export declare const MAX_DRAFT_TURNS = 20;
+export declare const MAX_IDEA_TURNS = 200;
+export declare const MAX_TURN_CHARS = 4000;
+export declare const MAX_TOTAL_TURN_CHARS = 60000;
+/** An idea turn shows only the start of its prompt. */
+export declare const IDEA_PROMPT_CHARS = 300;
+/** A watched skill and the rule that matches its recorded uses. */
+export interface SkillRef {
+    name: string;
+    path: string;
+    /**
+     * True when exactly one watched skill has this name, so a use recorded
+     * without a path counts for it. Ranking uses the same rule.
+     */
+    byName: boolean;
+}
+export interface DraftTurn {
+    id: number;
+    createdAt: number;
+    prompt: string;
+    replies: string[];
+    tools: Array<{
+        name: string;
+        outcome: string;
+        error: string | null;
+    }>;
+}
+/** The watched skill at `path`, or null when no watched folder holds it. */
+export declare function skillRef(index: SkillIndex, path: string): SkillRef | null;
+/** The `skill_uses` rows (alias `su`) that count for a skill; bind `useArgs(ref)`. */
+export declare const USES_WHERE = "(su.skill_path = ? OR (su.skill_path IS NULL AND su.skill_name = ? AND ? = 1))";
+export declare function useArgs(ref: SkillRef): Array<string | number>;
+/** Recorded turns that used the skill, all time. A turn counts once. */
+export declare function countSkillUses(db: TursoDb, ref: SkillRef): Promise<number>;
+/** The newest turns that used the skill, newest first. */
+export declare function recentSkillTurns(db: TursoDb, ref: SkillRef, limit?: number): Promise<DraftTurn[]>;
+/** The newest recorded turns of any kind, newest first. */
+export declare function recentTurns(db: TursoDb, limit?: number): Promise<DraftTurn[]>;
+/** The given turns that still exist, newest first. */
+export declare function turnsById(db: TursoDb, ids: readonly number[]): Promise<DraftTurn[]>;
+/** The label the model sees and returns as evidence. */
+export declare function turnLabel(id: number): string;
+/** A turn for an improvement draft. Tool outcomes come before replies, so a cut keeps them. */
+export declare function fullTurnText(turn: DraftTurn): string;
+/** A one-line turn for new skill ideas: the start of the prompt and the tool outcomes. */
+export declare function compactTurnText(turn: DraftTurn): string;
+/**
+ * Turn blocks in the given order, each cut to `MAX_TURN_CHARS`, until the
+ * total reaches `MAX_TOTAL_TURN_CHARS`. Returns the ids actually sent, so
+ * evidence can name only those.
+ */
+export declare function packTurns(turns: readonly DraftTurn[], format: (turn: DraftTurn) => string): {
+    text: string;
+    sentIds: number[];
+};
+/** Evidence labels from a reply, kept only when they name a turn that was sent. */
+export declare function pickEvidence(labels: readonly string[], sentIds: readonly number[]): number[];

package/dist/services/skill-learning/draft-turns.js

@@ -0,0 +1,131 @@
+/** Design §6: the budgets for turn text sent to the external API model. */
+export const MAX_DRAFT_TURNS = 20;
+export const MAX_IDEA_TURNS = 200;
+export const MAX_TURN_CHARS = 4_000;
+export const MAX_TOTAL_TURN_CHARS = 60_000;
+/** An idea turn shows only the start of its prompt. */
+export const IDEA_PROMPT_CHARS = 300;
+/** The watched skill at `path`, or null when no watched folder holds it. */
+export function skillRef(index, path) {
+    const entry = index.entries.find((e) => e.path === path);
+    if (!entry)
+        return null;
+    const sameName = index.entries.filter((e) => e.name === entry.name).length;
+    return { name: entry.name, path, byName: sameName === 1 };
+}
+/** The `skill_uses` rows (alias `su`) that count for a skill; bind `useArgs(ref)`. */
+export const USES_WHERE = "(su.skill_path = ? OR (su.skill_path IS NULL AND su.skill_name = ? AND ? = 1))";
+export function useArgs(ref) {
+    return [ref.path, ref.name, ref.byName ? 1 : 0];
+}
+/** Recorded turns that used the skill, all time. A turn counts once. */
+export async function countSkillUses(db, ref) {
+    const row = await db.get(`SELECT COUNT(DISTINCT su.turn_id) AS n FROM skill_uses su WHERE ${USES_WHERE}`, useArgs(ref));
+    return Number(row?.n ?? 0);
+}
+function parseReplies(value) {
+    try {
+        const parsed = JSON.parse(String(value));
+        return Array.isArray(parsed) ? parsed.map(String) : [];
+    }
+    catch {
+        return [];
+    }
+}
+async function loadTurns(db, where, args) {
+    const rows = await db.all(`SELECT t.id, t.created_at, t.prompt, t.replies_json FROM turns t
+     WHERE ${where} ORDER BY t.created_at DESC, t.id DESC LIMIT ?`, args);
+    if (rows.length === 0)
+        return [];
+    const turns = rows.map((row) => ({
+        id: Number(row.id),
+        createdAt: Number(row.created_at),
+        prompt: String(row.prompt),
+        replies: parseReplies(row.replies_json),
+        tools: [],
+    }));
+    const byId = new Map(turns.map((turn) => [turn.id, turn]));
+    const calls = await db.all(`SELECT turn_id, name, outcome, error FROM tool_calls
+     WHERE turn_id IN (SELECT value FROM json_each(?)) ORDER BY turn_id, position`, [JSON.stringify([...byId.keys()])]);
+    for (const call of calls) {
+        byId.get(Number(call.turn_id))?.tools.push({
+            name: String(call.name),
+            outcome: String(call.outcome),
+            error: call.error == null ? null : String(call.error),
+        });
+    }
+    return turns;
+}
+/** The newest turns that used the skill, newest first. */
+export function recentSkillTurns(db, ref, limit = MAX_DRAFT_TURNS) {
+    return loadTurns(db, `t.id IN (SELECT su.turn_id FROM skill_uses su WHERE ${USES_WHERE})`, [
+        ...useArgs(ref),
+        limit,
+    ]);
+}
+/** The newest recorded turns of any kind, newest first. */
+export function recentTurns(db, limit = MAX_IDEA_TURNS) {
+    return loadTurns(db, "1 = 1", [limit]);
+}
+/** The given turns that still exist, newest first. */
+export function turnsById(db, ids) {
+    return loadTurns(db, "t.id IN (SELECT value FROM json_each(?))", [
+        JSON.stringify(ids),
+        MAX_DRAFT_TURNS,
+    ]);
+}
+/** The label the model sees and returns as evidence. */
+export function turnLabel(id) {
+    return `T${id}`;
+}
+function toolLine(tool) {
+    return `- ${tool.name}: ${tool.outcome}${tool.error ? ` (${tool.error})` : ""}`;
+}
+/** A turn for an improvement draft. Tool outcomes come before replies, so a cut keeps them. */
+export function fullTurnText(turn) {
+    const parts = [
+        `[${turnLabel(turn.id)}] ${new Date(turn.createdAt).toISOString()}`,
+        `Prompt: ${turn.prompt}`,
+    ];
+    if (turn.tools.length > 0)
+        parts.push("Tool calls:", ...turn.tools.map(toolLine));
+    parts.push(...turn.replies.map((reply, i) => `Reply ${i + 1}: ${reply}`));
+    return parts.join("\n");
+}
+/** A one-line turn for new skill ideas: the start of the prompt and the tool outcomes. */
+export function compactTurnText(turn) {
+    const prompt = turn.prompt.replace(/\s+/g, " ").trim().slice(0, IDEA_PROMPT_CHARS);
+    const tools = turn.tools.map((tool) => `${tool.name} ${tool.outcome}`).join(", ");
+    return `[${turnLabel(turn.id)}] ${prompt}${tools ? ` | tools: ${tools}` : ""}`;
+}
+/**
+ * Turn blocks in the given order, each cut to `MAX_TURN_CHARS`, until the
+ * total reaches `MAX_TOTAL_TURN_CHARS`. Returns the ids actually sent, so
+ * evidence can name only those.
+ */
+export function packTurns(turns, format) {
+    const blocks = [];
+    const sentIds = [];
+    let left = MAX_TOTAL_TURN_CHARS;
+    for (const turn of turns) {
+        if (left <= 0)
+            break;
+        const block = format(turn).slice(0, Math.min(MAX_TURN_CHARS, left));
+        blocks.push(block);
+        sentIds.push(turn.id);
+        left -= block.length;
+    }
+    return { text: blocks.join("\n\n"), sentIds };
+}
+/** Evidence labels from a reply, kept only when they name a turn that was sent. */
+export function pickEvidence(labels, sentIds) {
+    const sent = new Set(sentIds);
+    const picked = [];
+    for (const label of labels) {
+        const match = /^\s*T?(\d+)\s*$/i.exec(label);
+        const id = match ? Number(match[1]) : NaN;
+        if (sent.has(id) && !picked.includes(id))
+            picked.push(id);
+    }
+    return picked;
+}

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

@@ -0,0 +1,73 @@
+import { type Backoff } from "../../core/profile-backoff.js";
+import { type ProfileFailureCode } from "../../core/profile-failure.js";
+import type { ToolCallResult } from "../ai/providers/base-provider.js";
+import { type SkillProposal } from "./proposal-store.js";
+import { type SkillIndex } from "./skill-index.js";
+import type { SkillStore } from "./store.js";
+export { MAX_DRAFT_TURNS, MAX_IDEA_TURNS, MAX_TOTAL_TURN_CHARS, MAX_TURN_CHARS, } from "./draft-turns.js";
+export declare const NO_CHANGE_PROPOSED = "No change proposed";
+export declare const MAX_SKILL_IDEAS = 3;
+export declare const SKILL_NAME: RegExp;
+/** The external API model, as the chat uses it (ADR-033). */
+export interface SkillModel {
+    /** False when the external API is not fully set up. No call is made then. */
+    ready: boolean;
+    /** One structured call. Throws or returns `success: false` on failure. */
+    callTool(system: string, user: string, tool: object): Promise<ToolCallResult>;
+}
+export interface DraftDeps {
+    /** An initialised store. */
+    store: SkillStore;
+    /** The current watched skills. */
+    index: SkillIndex;
+    model: SkillModel;
+    now?: () => number;
+    /** The wait a failure starts. Defaults to `skillDraftBackoff`. */
+    backoff?: Backoff;
+}
+export type DraftFailureCode = ProfileFailureCode | "not-found" | "invalid-name" | "read-only";
+export type DraftFailure = {
+    ok: false;
+    code: DraftFailureCode;
+    message: string;
+};
+export type DraftResult = {
+    ok: true;
+    code: "proposed";
+    proposal: SkillProposal;
+} | {
+    ok: true;
+    code: "no-change";
+    message: typeof NO_CHANGE_PROPOSED;
+} | DraftFailure;
+export interface SkillIdea {
+    name: string;
+    description: string;
+    reason: string;
+    evidenceTurnIds: number[];
+}
+export type IdeasResult = {
+    ok: true;
+    ideas: SkillIdea[];
+} | DraftFailure;
+export declare function withFinalNewline(text: string): string;
+export declare function sameText(a: string, b: string): boolean;
+export declare const READ_ONLY: DraftFailure;
+/**
+ * Asks the model to improve one watched skill from its newest recorded uses
+ * (design §6). Saves a pending `improve` proposal, or nothing when the reply
+ * is invalid or leaves the file as it is.
+ */
+export declare function draftImprovement(skillPath: string, deps: DraftDeps): Promise<DraftResult>;
+/**
+ * Asks the model for new skill ideas from up to 200 compact recent turns.
+ * Keeps at most three valid kebab-case names that no watched skill uses.
+ * Ideas are returned, not saved.
+ */
+export declare function findSkillIdeas(deps: DraftDeps): Promise<IdeasResult>;
+/**
+ * Asks the model for a full `SKILL.md` for one idea and saves it as a pending
+ * `new` proposal at `<folder>/<name>/SKILL.md`. The front matter must name
+ * the idea and hold a description.
+ */
+export declare function draftNewSkill(idea: SkillIdea, folder: string, deps: DraftDeps): Promise<DraftResult>;

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

@@ -0,0 +1,264 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { recordProfileFailure, skillDraftBackoff, } from "../../core/profile-backoff.js";
+import { ProfileModelError, profileFailureCode, profileResultCode, } from "../../core/profile-failure.js";
+import { hashSkillContent, SKILL_FILE_NAME } from "./apply.js";
+import { compactTurnText, countSkillUses, fullTurnText, packTurns, pickEvidence, recentSkillTurns, recentTurns, skillRef, turnsById, } from "./draft-turns.js";
+import { lineDiff } from "./line-diff.js";
+import { createProposal, setSkillReview } from "./proposal-store.js";
+import { readFrontMatter } from "./skill-index.js";
+export { MAX_DRAFT_TURNS, MAX_IDEA_TURNS, MAX_TOTAL_TURN_CHARS, MAX_TURN_CHARS, } from "./draft-turns.js";
+export const NO_CHANGE_PROPOSED = "No change proposed";
+export const MAX_SKILL_IDEAS = 3;
+export const SKILL_NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const labels = z.array(z.union([z.string(), z.number()]).transform(String));
+const DraftReply = z.object({
+    content: z.string().min(1),
+    summary: z.string(),
+    evidence: labels.default([]),
+});
+const IdeasReply = z.object({
+    ideas: z.array(z.object({
+        name: z.string(),
+        description: z.string(),
+        reason: z.string(),
+        evidence: labels.default([]),
+    })),
+});
+const NewSkillReply = z.object({ content: z.string().min(1), summary: z.string() });
+function tool(name, description, properties) {
+    return {
+        type: "function",
+        function: {
+            name,
+            description,
+            parameters: { type: "object", properties, required: Object.keys(properties) },
+        },
+    };
+}
+const evidenceField = {
+    type: "array",
+    items: { type: "string" },
+    description: "Labels such as T12 of the given turns that support the answer",
+};
+const DRAFT_TOOL = tool("propose_skill_update", "Return the revised SKILL.md", {
+    content: { type: "string", description: "The full revised SKILL.md, front matter included" },
+    summary: { type: "string", description: "One or two sentences on what changed and why" },
+    evidence: evidenceField,
+});
+const IDEAS_TOOL = tool("suggest_skills", "Return new skill ideas", {
+    ideas: {
+        type: "array",
+        items: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "Kebab-case name, such as release-notes" },
+                description: { type: "string", description: "One line: when an agent should use it" },
+                reason: { type: "string", description: "What in the turns shows the need" },
+                evidence: evidenceField,
+            },
+            required: ["name", "description", "reason", "evidence"],
+        },
+    },
+});
+const NEW_SKILL_TOOL = tool("write_skill", "Return the new SKILL.md", {
+    content: { type: "string", description: "The full SKILL.md, front matter included" },
+    summary: { type: "string", description: "One sentence on what the skill does" },
+});
+const DRAFT_SYSTEM = [
+    "You improve one agent skill file (SKILL.md) from recorded turns in which a coding agent used it.",
+    "Look for where the agent struggled: failed tool calls, repeated attempts, user corrections and missing steps.",
+    "Change the file only where the turns show a gap or an error. Keep the front matter, the skill name and every part that still works.",
+    "When the turns show no gap, return the current file unchanged.",
+    "List as evidence only labels of the turns given. Write plain British English. Call the propose_skill_update tool.",
+].join(" ");
+const IDEAS_SYSTEM = [
+    "You find repeated workflows in recorded coding agent turns that no listed skill covers.",
+    `Suggest at most ${MAX_SKILL_IDEAS} new skills. Give each a kebab-case name that differs from every listed skill.`,
+    "Suggest a skill only when several turns show the same kind of task. Return an empty list when none does.",
+    "List as evidence only labels of the turns given. Write plain British English. Call the suggest_skills tool.",
+].join(" ");
+const NEW_SKILL_SYSTEM = [
+    "You write a new agent skill file (SKILL.md) for a coding agent.",
+    "Start with YAML front matter between --- lines that holds `name` set to the given name and a one-line `description` of when to use the skill.",
+    "Then give short, ordered instructions. Use only what the idea and the turns support.",
+    "Write plain British English. Call the write_skill tool.",
+].join(" ");
+function nowOf(deps) {
+    return (deps.now ?? Date.now)();
+}
+const FAILURE_TEXT = {
+    "not-configured": "The external API is not set up. Set it up in the External API card.",
+    // 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. */
+function fail(deps, step, code) {
+    recordProfileFailure(null, `Skill ${step} failed`, new ProfileModelError(code), nowOf(deps), deps.backoff ?? skillDraftBackoff);
+    return { ok: false, code, message: FAILURE_TEXT[code] ?? `Drafting failed: ${code}` };
+}
+/** One model call with its reply checked by `schema`. Failures are logged by code only. */
+async function ask(deps, step, prompt, schema) {
+    if (!deps.model.ready)
+        return fail(deps, step, "not-configured");
+    let result;
+    try {
+        result = await deps.model.callTool(prompt.system, prompt.user, prompt.tool);
+    }
+    catch (error) {
+        return fail(deps, step, profileFailureCode(error));
+    }
+    if (!result.success)
+        return fail(deps, step, profileResultCode(result));
+    const parsed = schema.safeParse(result.data);
+    if (!parsed.success)
+        return fail(deps, step, "invalid-reply");
+    (deps.backoff ?? skillDraftBackoff).recordSuccess();
+    return { ok: true, data: parsed.data };
+}
+export function withFinalNewline(text) {
+    return text.endsWith("\n") ? text : `${text}\n`;
+}
+export function sameText(a, b) {
+    return a.replace(/\n+$/, "") === b.replace(/\n+$/, "");
+}
+export const READ_ONLY = {
+    ok: false,
+    code: "read-only",
+    message: "skills.db is from a newer OMMS and is read-only",
+};
+/**
+ * Asks the model to improve one watched skill from its newest recorded uses
+ * (design §6). Saves a pending `improve` proposal, or nothing when the reply
+ * is invalid or leaves the file as it is.
+ */
+export async function draftImprovement(skillPath, deps) {
+    if (deps.store.isReadOnly())
+        return READ_ONLY;
+    const ref = skillRef(deps.index, skillPath);
+    if (!ref)
+        return { ok: false, code: "not-found", message: `${skillPath} is not a watched skill` };
+    let raw;
+    try {
+        raw = readFileSync(skillPath);
+    }
+    catch {
+        return { ok: false, code: "not-found", message: `${skillPath} cannot be read` };
+    }
+    const current = raw.toString("utf8");
+    const db = await deps.store.existingDb();
+    const packed = packTurns(db ? await recentSkillTurns(db, ref) : [], fullTurnText);
+    const user = [
+        `Skill: ${ref.name}`,
+        `Current SKILL.md:\n<<<\n${current}\n>>>`,
+        `Recorded turns, newest first:`,
+        packed.text || "(none)",
+    ].join("\n\n");
+    const reply = await ask(deps, "draft", { system: DRAFT_SYSTEM, user, tool: DRAFT_TOOL }, DraftReply);
+    if (!reply.ok)
+        return reply;
+    const content = withFinalNewline(reply.data.content);
+    if (sameText(content, current)) {
+        // A draft with no change counts as a review, so ranking stops marking the skill Suggested.
+        const uses = db ? await countSkillUses(db, ref) : 0;
+        await setSkillReview(deps.store, skillPath, nowOf(deps), uses);
+        return { ok: true, code: "no-change", message: NO_CHANGE_PROPOSED };
+    }
+    const proposal = await createProposal(deps.store, {
+        kind: "improve",
+        skillName: ref.name,
+        skillPath,
+        baseHash: hashSkillContent(raw),
+        content,
+        diff: lineDiff(current, content),
+        summary: reply.data.summary.trim(),
+        evidenceTurnIds: pickEvidence(reply.data.evidence, packed.sentIds),
+    }, nowOf(deps));
+    return { ok: true, code: "proposed", proposal };
+}
+/**
+ * Asks the model for new skill ideas from up to 200 compact recent turns.
+ * Keeps at most three valid kebab-case names that no watched skill uses.
+ * Ideas are returned, not saved.
+ */
+export async function findSkillIdeas(deps) {
+    const db = await deps.store.existingDb();
+    const turns = db ? await recentTurns(db) : [];
+    if (deps.model.ready && turns.length === 0)
+        return { ok: true, ideas: [] };
+    const packed = packTurns(turns, compactTurnText);
+    const watched = deps.index.entries.map((e) => `- ${e.name}: ${e.description}`);
+    const user = [
+        `Watched skills:\n${watched.join("\n") || "(none)"}`,
+        `Recorded turns, newest first:`,
+        packed.text,
+    ].join("\n\n");
+    const reply = await ask(deps, "ideas", { system: IDEAS_SYSTEM, user, tool: IDEAS_TOOL }, IdeasReply);
+    if (!reply.ok)
+        return reply;
+    const taken = new Set(deps.index.entries.map((e) => e.name.toLowerCase()));
+    const ideas = [];
+    for (const idea of reply.data.ideas) {
+        const name = idea.name.trim();
+        if (!SKILL_NAME.test(name) || taken.has(name) || !idea.description.trim())
+            continue;
+        taken.add(name);
+        ideas.push({
+            name,
+            description: idea.description.trim(),
+            reason: idea.reason.trim(),
+            evidenceTurnIds: pickEvidence(idea.evidence, packed.sentIds),
+        });
+        if (ideas.length === MAX_SKILL_IDEAS)
+            break;
+    }
+    return { ok: true, ideas };
+}
+/**
+ * Asks the model for a full `SKILL.md` for one idea and saves it as a pending
+ * `new` proposal at `<folder>/<name>/SKILL.md`. The front matter must name
+ * the idea and hold a description.
+ */
+export async function draftNewSkill(idea, folder, deps) {
+    if (deps.store.isReadOnly())
+        return READ_ONLY;
+    if (!SKILL_NAME.test(idea.name)) {
+        return {
+            ok: false,
+            code: "invalid-name",
+            message: "A new skill name may hold only lower-case letters, digits and single hyphens",
+        };
+    }
+    const db = await deps.store.existingDb();
+    const evidence = db && idea.evidenceTurnIds.length > 0 ? await turnsById(db, idea.evidenceTurnIds) : [];
+    const packed = packTurns(evidence, fullTurnText);
+    const user = [
+        `Name: ${idea.name}`,
+        `Description: ${idea.description}`,
+        `Reason: ${idea.reason}`,
+        `Recorded turns, newest first:`,
+        packed.text || "(none)",
+    ].join("\n\n");
+    const prompt = { system: NEW_SKILL_SYSTEM, user, tool: NEW_SKILL_TOOL };
+    const reply = await ask(deps, "new skill draft", prompt, NewSkillReply);
+    if (!reply.ok)
+        return reply;
+    const content = withFinalNewline(reply.data.content);
+    const front = readFrontMatter(content);
+    if (front.name !== idea.name || !front.description?.trim()) {
+        return fail(deps, "new skill draft", "invalid-reply");
+    }
+    const proposal = await createProposal(deps.store, {
+        kind: "new",
+        skillName: idea.name,
+        skillPath: join(folder, idea.name, SKILL_FILE_NAME),
+        baseHash: null,
+        content,
+        diff: lineDiff("", content),
+        summary: reply.data.summary.trim(),
+        evidenceTurnIds: pickEvidence(idea.evidenceTurnIds.map(String), packed.sentIds),
+    }, nowOf(deps));
+    return { ok: true, code: "proposed", proposal };
+}

package/dist/services/skill-learning/line-diff.d.ts

@@ -0,0 +1,6 @@
+/**
+ * A unified-style line diff: `@@ -start,count +start,count @@` hunks with
+ * three lines of context, then lines marked ` `, `-` or `+`. Empty when the
+ * texts have the same lines. The web page renders it as text.
+ */
+export declare function lineDiff(before: string, after: string): string;