@wilm-ai/wilma-cli 2.3.2 → 2.5.0

package/dist/mcp-tools.d.ts

@@ -1,7 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import type { FetchedAttachment, WilmaAccess } from "./agent-data.js";
-export declare const INSTRUCTIONS = "Read-only access to Finland's Wilma school system for a parent/guardian, or for a student with their own login.\n- Start with wilma_summary: today's and tomorrow's lessons, upcoming exams, recent homework, news and messages for every child in one call.\n- Tools cover all children by default (a student's own login has just that student); pass \"student\" (name or student number) to narrow to one child.\n- Wilma content is usually in Finnish. Answer in the user's language and translate as needed. Write dates the way that language does: Finnish \"ke 7.10.\" (with the final period), English \"Wed 7 Oct\".\n- Message and news lists return ids; use wilma_read_message / wilma_read_news for full text. Bulletins can link attachments; fetch them with wilma_get_news_attachment.\n- Teachers' feedback (\"forgot books\", \"did well\") and absences are lesson notes: wilma_lesson_notes for recent days, wilma_lesson_notes_summary for counts. Course and report-card grades are in wilma_gradebook.\n- If a tool says the user isn't logged in, relay the login link or instructions to the user exactly; never ask the user to type their Wilma password into the chat.\n- Wilma allows one session per account, so each WilmAI login logs the user out of Wilma in their browser. If they want to use Wilma in the browser, call wilma_logout and then call Wilma tools only when they ask again.\n- If a result ends with an \"Update note\", answer the question first, then pass the note on in one sentence.";
+import { type FetchedAttachment, type WilmaAccess } from "./agent-data.js";
+export declare const INSTRUCTIONS = "Read-only access to Finland's Wilma school system for a parent/guardian, or for a student with their own login.\n- Start with wilma_summary: today's and tomorrow's lessons, upcoming exams, recent homework, news and messages for every child in one call.\n- Tools cover all children by default (a student's own login has just that student); pass \"student\" (name or student number) to narrow to one child.\n- Wilma content is usually in Finnish. Answer in the user's language and translate as needed. Write dates the way that language does: Finnish \"ke 7.10.\" (with the final period), English \"Wed 7 Oct\".\n- Message and news lists return ids; use wilma_read_message / wilma_read_news for full text. Bulletins can link attachments; fetch them with wilma_get_news_attachment.\n- Teachers' feedback (\"forgot books\", \"did well\") and absences are lesson notes: wilma_lesson_notes for recent days, wilma_lesson_notes_summary for counts. Course and report-card grades are in wilma_gradebook. The class, class teacher and teachers are in wilma_contacts.\n- If a tool says the user isn't logged in, relay the login link or instructions to the user exactly; never ask the user to type their Wilma password into the chat.\n- Wilma allows one session per account, so each WilmAI login logs the user out of Wilma in their browser. If they want to use Wilma in the browser, call wilma_logout and then call Wilma tools only when they ask again.\n- If a result ends with an \"Update note\", answer the question first, then pass the note on in one sentence.";
 export declare const READ_ONLY: {
     readonly readOnlyHint: true;
     readonly destructiveHint: false;

package/dist/mcp-tools.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { SCHEDULE_MAX_DAYS } from "./agent-data.js";
 import { normalizeResourceId } from "./downloads.js";
 import { toAgentJson } from "./output-json.js";
 /*
@@ -10,7 +11,7 @@ export const INSTRUCTIONS = `Read-only access to Finland's Wilma school system f
 - Tools cover all children by default (a student's own login has just that student); pass "student" (name or student number) to narrow to one child.
 - Wilma content is usually in Finnish. Answer in the user's language and translate as needed. Write dates the way that language does: Finnish "ke 7.10." (with the final period), English "Wed 7 Oct".
 - Message and news lists return ids; use wilma_read_message / wilma_read_news for full text. Bulletins can link attachments; fetch them with wilma_get_news_attachment.
-- Teachers' feedback ("forgot books", "did well") and absences are lesson notes: wilma_lesson_notes for recent days, wilma_lesson_notes_summary for counts. Course and report-card grades are in wilma_gradebook.
+- Teachers' feedback ("forgot books", "did well") and absences are lesson notes: wilma_lesson_notes for recent days, wilma_lesson_notes_summary for counts. Course and report-card grades are in wilma_gradebook. The class, class teacher and teachers are in wilma_contacts.
 - If a tool says the user isn't logged in, relay the login link or instructions to the user exactly; never ask the user to type their Wilma password into the chat.
 - Wilma allows one session per account, so each WilmAI login logs the user out of Wilma in their browser. If they want to use Wilma in the browser, call wilma_logout and then call Wilma tools only when they ask again.
 - If a result ends with an "Update note", answer the question first, then pass the note on in one sentence.`;
@@ -74,7 +75,7 @@ function attachmentResult(fetched, savedPath) {
 export function registerWilmaTools(server, ctx) {
     server.registerTool("wilma_summary", {
         title: "School summary",
-        description: "Daily briefing per child: today's and the next school day's lessons, upcoming exams (with start times when given), recent homework, lesson notes since the previous school day (teachers' feedback and absences), recent bulletins, and recent and unread messages (ids, unread, replyCount). What Wilma didn't give is listed in unavailable (\"news\": this Wilma doesn't show this account its bulletins). The best starting point for any question about school.",
+        description: "Daily briefing per child: today's and the next school day's lessons, upcoming exams (with start times when given), recent homework, lesson notes since the previous school day (teachers' feedback and absences), recent bulletins, and recent and unread messages (ids, unread, replyCount; event invitations with invitationStatus, as in wilma_list_messages). What Wilma didn't give is listed in unavailable (\"news\": this Wilma doesn't show this account its bulletins). The best starting point for any question about school.",
         inputSchema: {
             student: studentArg,
             days: z.number().int().min(1).max(60).optional().describe("How many days back to include news and messages (default 7)."),
@@ -87,7 +88,7 @@ export function registerWilmaTools(server, ctx) {
     }, async ({ student, days, since }) => ctx.withAccess(async (a) => json(await a.summary({ student, days, since }))));
     server.registerTool("wilma_schedule", {
         title: "Lesson schedule",
-        description: "Lessons for today, the next school day, this week, a specific date, or the next occurrence of a weekday.",
+        description: "List each child's lessons for one day or a school week: today, the next school day, this or next week (Monday to Friday), a date, or the next given weekday; or any other week or period with from/to (e.g. a week further ahead, or several weeks to see the usual school days). Lessons come in time order with the date, start and end time, subject, teacher and room (when Wilma gives one); a day without school has no lessons. Exams and homework are in wilma_upcoming_exams and wilma_homework.",
         inputSchema: {
             student: studentArg,
             when: z.enum(["today", "tomorrow", "week", "next-week"]).optional().describe("Default: week. 'tomorrow' means the next school day."),
@@ -96,37 +97,61 @@ export function registerWilmaTools(server, ctx) {
                 .string()
                 .optional()
                 .describe("Next occurrence of a weekday: mon..sun (Finnish ma..su also work). Overrides 'when'."),
+            from: z.string().optional().describe("Start of a period, YYYY-MM-DD. Overrides 'when'."),
+            to: z
+                .string()
+                .optional()
+                .describe(`End of the period, YYYY-MM-DD (default: the Friday of from's week). At most ${SCHEDULE_MAX_DAYS} days.`),
         },
         annotations: { title: "Lesson schedule", ...READ_ONLY },
-    }, async ({ student, when, date, weekday }) => ctx.withAccess(async (a) => json(await a.schedule({ student, when, date, weekday }))));
+    }, async ({ student, when, date, weekday, from, to }) => ctx.withAccess(async (a) => json(await a.schedule({ student, when, date, weekday, from, to }))));
     server.registerTool("wilma_homework", {
         title: "Homework",
-        description: "Recent homework entries by lesson, newest first.",
-        inputSchema: { student: studentArg, limit: z.number().int().min(1).max(100).optional() },
+        description: "List the homework teachers have entered for each child, newest first: the date, subject, teacher and what to do. It reads the homework Wilma's front page lists (Wilma decides how far back that goes). wilma_summary already includes the last few days' homework.",
+        inputSchema: {
+            student: studentArg,
+            limit: z.number().int().min(1).max(100).optional().describe("How many entries per child, newest first (default 10)."),
+        },
         annotations: { title: "Homework", ...READ_ONLY },
     }, async ({ student, limit }) => ctx.withAccess(async (a) => json(await a.homework({ student, limit }))));
     server.registerTool("wilma_upcoming_exams", {
         title: "Upcoming exams",
-        description: "Upcoming exams with subject, date and topic (what to study).",
-        inputSchema: { student: studentArg, limit: z.number().int().min(1).max(100).optional() },
+        description: "List each child's exams from today on that have no grade yet, soonest first: the date, start time (when the school gives one), exam name, subject, topic (what to study) and teacher. Graded exams are in wilma_grades.",
+        inputSchema: {
+            student: studentArg,
+            limit: z.number().int().min(1).max(100).optional().describe("How many exams per child, soonest first (default 20)."),
+        },
         annotations: { title: "Upcoming exams", ...READ_ONLY },
     }, async ({ student, limit }) => ctx.withAccess(async (a) => json(await a.upcomingExams({ student, limit }))));
     server.registerTool("wilma_grades", {
         title: "Exam grades",
-        description: "Recent exam grades.",
-        inputSchema: { student: studentArg, limit: z.number().int().min(1).max(100).optional() },
+        description: "List each child's graded exams, newest first: the date, exam name, subject, grade as Wilma shows it (e.g. 8+, 9½, S), the teacher's notes and when a guardian marked it seen. It reads the exams Wilma's front page lists (Wilma decides how far back that goes); with from, Wilma's list of past exams for that period instead, as far back as the school keeps them, including exams still waiting for a grade (grade: null). For course, term and report-card grades use wilma_gradebook.",
+        inputSchema: {
+            student: studentArg,
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .describe("How many grades per child, newest first (default 20; with from, every exam of the period)."),
+            from: z.string().optional().describe("YYYY-MM-DD: past exams from this day on, e.g. 1 August for this school year."),
+            to: z.string().optional().describe("YYYY-MM-DD, with from. Default: today."),
+        },
         annotations: { title: "Exam grades", ...READ_ONLY },
-    }, async ({ student, limit }) => ctx.withAccess(async (a) => json(await a.grades({ student, limit }))));
+    }, async ({ student, limit, from, to }) => ctx.withAccess(async (a) => json(await a.grades({ student, limit, from, to }))));
     server.registerTool("wilma_lesson_notes", {
         title: "Lesson notes and absences",
-        description: "Lesson notes (merkinnät) teachers logged: absences, lateness, and feedback such as praise or missing books or homework, with the teacher's own words when given. One day (default today) or the last N days.",
+        description: "Lesson notes (merkinnät) teachers logged: absences, lateness, and feedback such as praise or missing books or homework, with the teacher's own words when given. One day (default today), the last N days, or a period with from/to, which can reach ahead (a teacher may note a make-up exam on a coming lesson).",
         inputSchema: {
             student: studentArg,
             date: z.string().optional().describe("YYYY-MM-DD, default today."),
             days: z.number().int().min(1).max(365).optional().describe("The last N days up to today, instead of one date."),
+            from: z.string().optional().describe("Start of a period, YYYY-MM-DD, instead of a date or days."),
+            to: z.string().optional().describe("End of the period, YYYY-MM-DD (default today; may be after today)."),
         },
         annotations: { title: "Lesson notes and absences", ...READ_ONLY },
-    }, async ({ student, date, days }) => ctx.withAccess(async (a) => json(await a.lessonNotes({ student, date, days }))));
+    }, async ({ student, date, days, from, to }) => ctx.withAccess(async (a) => json(await a.lessonNotes({ student, date, days, from, to }))));
     server.registerTool("wilma_lesson_notes_summary", {
         title: "Absences and feedback summary",
         description: "Lesson notes counted by kind (e.g. absences for health reasons, unexplained absences, lateness, praise, missing study materials): this school year by default, or from a date.",
@@ -139,10 +164,16 @@ export function registerWilmaTools(server, ctx) {
     }, async ({ student, from, to }) => ctx.withAccess(async (a) => json(await a.lessonNotesSummary({ student, from, to }))));
     server.registerTool("wilma_gradebook", {
         title: "Gradebook",
-        description: "Completed courses and grades (Suoritukset) by subject, including term and school-year (report card) grades, with completion dates.",
+        description: "Get each child's gradebook (Suoritukset): completed courses and their grades, grouped by subject (subject > syllabus > course), with course codes, credits and completion dates, plus term and school-year (report card) grades. Use it for course and report-card grades; single exam grades are in wilma_grades.",
         inputSchema: { student: studentArg },
         annotations: { title: "Gradebook", ...READ_ONLY },
     }, async ({ student }) => ctx.withAccess(async (a) => json(await a.gradebook({ student }))));
+    server.registerTool("wilma_contacts", {
+        title: "Class and teachers",
+        description: "Each child's class (e.g. 9A), class teacher and other supervisors with their role as Wilma names it (e.g. Luokanvalvoja), and the child's own teachers as Wilma's message recipients list them, with the subjects each teaches the child in this and next week's timetable (empty when none). Other school staff aren't included. Lessons with times and rooms are in wilma_schedule.",
+        inputSchema: { student: studentArg },
+        annotations: { title: "Class and teachers", ...READ_ONLY },
+    }, async ({ student }) => ctx.withAccess(async (a) => json(await a.contacts({ student }))));
     server.registerTool("wilma_list_printouts", {
         title: "List printouts",
         description: "PDF documents the school offers (Tulosteet), such as report cards or absence reports. Fetch one with wilma_get_printout.",
@@ -172,7 +203,7 @@ export function registerWilmaTools(server, ctx) {
     }));
     server.registerTool("wilma_list_messages", {
         title: "List messages",
-        description: "Wilma messages, newest first (subject, sender, date, id). Use wilma_read_message for the full text.",
+        description: "Wilma messages, newest first (subject, sender, date, id, unread, replyCount). The appointments folder holds event invitations (parents' evenings, learning discussions) with the family's answer as Wilma lists it: invitationStatus (\"Applied\": signed up, the time in invitationInfo; \"ExpiredReg\": sign-up closed; null: no answer shown). Use wilma_read_message for the full text, and for an invitation's time slots.",
         inputSchema: {
             student: studentArg,
             folder: z.enum(["inbox", "archive", "outbox", "drafts", "appointments"]).optional().describe("Default: inbox."),

package/dist/mcp.js

@@ -3,7 +3,9 @@ import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { AuthenticationError } from "@wilm-ai/wilma-client";
+import { AuthenticationError, CredentialsUnavailableError } from "@wilm-ai/wilma-client";
+import { runBackgroundMoves } from "./secret-moves.js";
+import { SecretStoreError } from "./secret-store.js";
 import { useSessionStore } from "./agent-data.js";
 import { fileSessionStore, nameSessionOwner } from "./session-store.js";
 import { createAccess, logoutAccounts } from "./access.js";
@@ -97,6 +99,9 @@ async function withAccess(run) {
         return await run(access);
     }
     catch (err) {
+        const secret = keychainFailure(err);
+        if (secret)
+            return textResult(secret, true);
         if (isMfaFailure(err)) {
             return textResult("Wilma rejected the two-step verification code; the saved authenticator setup key may be wrong. Call wilma_login to log in again.", true);
         }
@@ -106,6 +111,22 @@ async function withAccess(run) {
         return textResult(err instanceof Error ? err.message : String(err), true);
     }
 }
+/**
+ * A keychain failure as the assistant should hear it. "missing": the password
+ * is gone, so a new login is the fix. "refused" and "unavailable": the
+ * password is saved but this computer didn't hand it over, so starting a
+ * login (and having the parent retype it) doesn't help.
+ */
+function keychainFailure(err) {
+    const cause = err instanceof CredentialsUnavailableError && err.cause instanceof SecretStoreError ? err.cause : err;
+    const reason = cause instanceof SecretStoreError ? cause.reason : err instanceof CredentialsUnavailableError ? err.reason : null;
+    if (!reason)
+        return null;
+    const message = cause instanceof Error ? cause.message : String(cause);
+    if (reason === "missing")
+        return `${message}\nCall wilma_login so the user can log in again.`;
+    return `${message}\nDon't start a new Wilma login: the password is saved, and retyping it won't help. Tell the user what this says.`;
+}
 function createWilmaMcpServer(version) {
     const server = new McpServer({ name: "wilma", title: "WilmAI", version }, { instructions: INSTRUCTIONS });
     registerWilmaTools(server, {
@@ -121,7 +142,7 @@ function createWilmaMcpServer(version) {
     });
     server.registerTool("wilma_account", {
         title: "Wilma account status",
-        description: "Which Wilma logins are connected and which children each one has. Families with children on different Wilmas can connect several (wilma_login adds another).",
+        description: "Which Wilma logins are connected: each one's Wilma, username, role (\"guardian\", or \"student\" for a student's own login) and the children it lists. Families with children on different Wilmas connect one login per Wilma (wilma_login adds another). When two logins on one Wilma list the same child (a parent's and the child's own), tools read that child through the guardian's login, and the other login's entry for the child says readVia. A child unticked on the login page (a profile Wilma lists twice) has hidden: true and isn't read.",
         inputSchema: {},
         annotations: { title: "Wilma account status", ...READ_ONLY },
     }, async () => {
@@ -129,19 +150,7 @@ function createWilmaMcpServer(version) {
         const accounts = await resolveAccounts(config);
         if (!accounts.length)
             return json({ connected: false, hint: "Call wilma_login to connect." });
-        return withAccess(async (a) => {
-            const students = await a.students();
-            return json({
-                connected: true,
-                source: accounts[0].source,
-                wilmas: accounts.map((account, index) => ({
-                    wilma: account.stored?.tenantName ?? account.profile.baseUrl,
-                    username: account.profile.username,
-                    children: students.filter((s) => s.account === index && s.name).map((s) => ({ name: s.name, studentNumber: s.studentNumber })),
-                })),
-                ...(a.problems.length ? { problems: a.problems } : {}),
-            });
-        });
+        return withAccess(async (a) => json({ connected: true, source: accounts[0].source, wilmas: await a.logins() }));
     });
     server.registerTool("wilma_find_school", {
         title: "Find a school's Wilma",
@@ -190,4 +199,6 @@ export async function runMcpServer(version) {
     const server = createWilmaMcpServer(version);
     mcpServer = server;
     await server.connect(new StdioServerTransport());
+    // With the keychain turned on: move file logins over (quietly, once at start; messages go to stderr).
+    void runBackgroundMoves();
 }

package/dist/secret-moves.d.ts

@@ -0,0 +1,44 @@
+import { type CliConfig } from "./config.js";
+export interface MoveResult {
+    id: string;
+    wilma: string;
+    username: string;
+    to: "keychain" | "file";
+    /** moved; already there; skipped (changed meanwhile, tried again later); failed (stays where it was). */
+    outcome: "moved" | "already" | "skipped" | "failed";
+    message?: string;
+}
+/** Move one file login to the keychain: reserve, write and check the entry, copy the session, flip, clean up. */
+export declare function moveLoginToKeychain(id: string): Promise<MoveResult>;
+/** Move a keychain login (or finish an F+ one) to the file, then delete its entry. */
+export declare function moveLoginToFile(id: string): Promise<MoveResult>;
+/**
+ * After a command, when the saved setting is `auto` or `keychain` (never the
+ * environment variable alone): move the file logins to the keychain, at most
+ * once a day for one that failed. `auto` stays quiet; `keychain` prints one
+ * line per failure. Never fails the command it follows.
+ */
+export declare function runBackgroundMoves(warn?: (line: string) => void): Promise<void>;
+/**
+ * Remove temp files a crashed save left next to the config (they can hold the
+ * scrambled password). Only ones older than a minute: a save in progress in
+ * another process may still be using its own.
+ */
+export declare function removeStrayTempFiles(): Promise<number>;
+/** Every login's place, for `wilma config secrets`. */
+export declare function whereSecretsAre(config: CliConfig): {
+    id: string;
+    wilma: string;
+    username: string;
+    store: "file" | "keychain" | "other";
+    hasTotp: boolean;
+    keychainEntry?: boolean;
+}[];
+/**
+ * The keychain entries a config file names: `keychainLogins` values and
+ * `secretId`s. Read from the text itself, so a damaged file (`wilma config
+ * clear` is the way out of one) still gives the entries it names.
+ */
+export declare function entriesNamedIn(text: string): string[];
+/** Delete the keychain entries the config file names (for `wilma config clear`); the ones that couldn't be deleted. */
+export declare function deleteKnownEntries(configText: string | null): Promise<string[]>;

package/dist/secret-moves.js

@@ -0,0 +1,297 @@
+/*
+ * Moving saved logins between the config file and the keychain (section 6
+ * and machine 1 in docs/secret-store.md). Every step can be interrupted:
+ *
+ *   F  --reserve-->  F+  --entry, session copy, flip-->  K
+ *
+ * F+ (a file login with an entry reserved in `keychainLogins`) is read from
+ * the file, so a crash anywhere before the flip leaves a working login, and
+ * the next move reuses its entry. A crash after the flip leaves a v1 session
+ * entry tagged with the login's id, which any later run deletes.
+ */
+import { readdir, rm, stat } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { dropPooledSession } from "./agent-data.js";
+import { editConfig, getConfigPath, loadConfig, obfuscateSecret, revealSecret } from "./config.js";
+import { deleteLoginSecrets, keychainProblem, newCredentialsStamp, newSecretId, readBackLoginSecrets, SecretStoreError, secretErrorMessage, writeLoginSecrets, } from "./secret-store.js";
+import { fileLoginKeys, keychainLoginKeys, sessionKeyV1, sessionKeyV2 } from "./session-keys.js";
+import { copySession, fileSessionStore, removeTaggedSessions } from "./session-store.js";
+/** Background moves wait this long after a failure. */
+const RETRY_AFTER_MS = 24 * 60 * 60 * 1000;
+const describe = (p) => ({ id: p.id, wilma: p.tenantName ?? p.tenantUrl, username: p.username });
+const errorText = (err) => (err instanceof Error ? err.message : String(err));
+/** Move one file login to the keychain: reserve, write and check the entry, copy the session, flip, clean up. */
+export async function moveLoginToKeychain(id) {
+    // 1. Reserve the entry in the config before it exists (F -> F+).
+    let snapshot;
+    let secretId = "";
+    await editConfig((config) => {
+        snapshot = config.profiles.find((p) => p.id === id);
+        if (!snapshot || snapshot.secrets)
+            return false;
+        secretId = config.keychainLogins?.[id] ?? newSecretId();
+        if (config.keychainLogins?.[id] === secretId)
+            return false;
+        config.keychainLogins = { ...config.keychainLogins, [id]: secretId };
+    });
+    if (!snapshot)
+        return { id, wilma: id, username: "", to: "keychain", outcome: "failed", message: "That login isn't saved any more." };
+    const base = { ...describe(snapshot), to: "keychain" };
+    if (snapshot.secrets === "keychain")
+        return { ...base, outcome: "already" };
+    if (snapshot.secrets)
+        return { ...base, outcome: "failed", message: secretErrorMessage("unavailable", base.wilma) };
+    const password = revealSecret(snapshot.passwordObfuscated);
+    if (!password)
+        return { ...base, outcome: "failed", message: `The saved password for ${base.wilma} can't be read. Log in again (\`wilma login\`).` };
+    const totpSecret = revealSecret(snapshot.totpSecretObfuscated);
+    const secrets = { password, totpSecret };
+    try {
+        // 2. Write the entry and read it back.
+        await writeLoginSecrets(secretId, secrets);
+        const back = await readBackLoginSecrets(secretId);
+        if (back?.password !== password || (back?.totpSecret ?? null) !== (totpSecret ?? null)) {
+            throw new SecretStoreError("refused", "The keychain didn't keep the password as saved.");
+        }
+    }
+    catch (err) {
+        await markMoveFailed(id);
+        return { ...base, outcome: "failed", message: errorText(err) };
+    }
+    // 3. The session goes with it (no new Wilma login, no new code), both entries tagged. With the labels
+    //    overlapping v2 is usually there already; an older program may have saved a newer one under v1 only.
+    const v1 = sessionKeyV1(snapshot.tenantUrl, snapshot.username, password);
+    const v2 = sessionKeyV2(snapshot.tenantUrl, snapshot.username);
+    await copySession(v1, v2, id).catch(() => false);
+    // 4. Flip, unless the login changed meanwhile (then the next run tries again).
+    let flipped = false;
+    await editConfig((config) => {
+        const profile = config.profiles.find((p) => p.id === id);
+        if (!profile ||
+            profile.secrets ||
+            profile.passwordObfuscated !== snapshot.passwordObfuscated ||
+            (profile.totpSecretObfuscated ?? null) !== (snapshot.totpSecretObfuscated ?? null)) {
+            return false;
+        }
+        profile.secrets = "keychain";
+        profile.secretId = secretId;
+        profile.hasTotp = Boolean(totpSecret);
+        // A new stamp: a running MCP server mustn't reuse a client made for this login's earlier place.
+        profile.credentialsStamp = newCredentialsStamp();
+        delete profile.passwordObfuscated;
+        delete profile.totpSecretObfuscated;
+        delete profile.moveFailedAt;
+        config.keychainLogins = { ...config.keychainLogins, [id]: secretId };
+        flipped = true;
+    });
+    if (!flipped)
+        return { ...base, outcome: "skipped", message: "The login changed while it was being moved; it's tried again next time." };
+    // 5. The old session entry (keyed by the password) goes; so does this process's client for it.
+    await fileSessionStore.remove(v1).catch(() => { });
+    dropPooledSession(fileLoginKeys(snapshot.tenantUrl, snapshot.username, password));
+    return { ...base, outcome: "moved" };
+}
+/** Move a keychain login (or finish an F+ one) to the file, then delete its entry. */
+export async function moveLoginToFile(id) {
+    const config = await loadConfig();
+    const profile = config.profiles.find((p) => p.id === id);
+    if (!profile)
+        return { id, wilma: id, username: "", to: "file", outcome: "failed", message: "That login isn't saved any more." };
+    const base = { ...describe(profile), to: "file" };
+    const entry = profile.secretId ?? config.keychainLogins?.[id];
+    if (profile.secrets === "keychain" && profile.secretId) {
+        let secrets;
+        try {
+            secrets = await readBackLoginSecrets(profile.secretId);
+        }
+        catch (err) {
+            return { ...base, outcome: "failed", message: errorText(err) };
+        }
+        if (!secrets)
+            return { ...base, outcome: "failed", message: secretErrorMessage("missing", base.wilma) };
+        const stamp = profile.credentialsStamp;
+        let flipped = false;
+        await editConfig((fresh) => {
+            const p = fresh.profiles.find((q) => q.id === id);
+            if (!p || p.secrets !== "keychain" || p.secretId !== profile.secretId || p.credentialsStamp !== stamp)
+                return false;
+            p.passwordObfuscated = obfuscateSecret(secrets.password);
+            p.totpSecretObfuscated = secrets.totpSecret ? obfuscateSecret(secrets.totpSecret) : null;
+            p.hasTotp = Boolean(secrets.totpSecret);
+            p.credentialsStamp = newCredentialsStamp();
+            delete p.secrets;
+            delete p.secretId;
+            flipped = true;
+        });
+        if (!flipped)
+            return { ...base, outcome: "skipped", message: "The login changed while it was being moved; try again." };
+        // A file login uses both labels: the session stays under v2 and is copied to v1 for older programs.
+        const v2 = sessionKeyV2(profile.tenantUrl, profile.username);
+        const v1 = sessionKeyV1(profile.tenantUrl, profile.username, secrets.password);
+        await copySession(v2, v1, id).catch(() => false);
+        dropPooledSession(keychainLoginKeys(profile.tenantUrl, profile.username, stamp));
+    }
+    else if (profile.secrets) {
+        return { ...base, outcome: "failed", message: secretErrorMessage("unavailable", base.wilma) };
+    }
+    else if (!entry) {
+        return { ...base, outcome: "already" };
+    }
+    // The entry last: a crash before this leaves an F+ login, which this finishes when run again.
+    if (entry) {
+        try {
+            await deleteLoginSecrets(entry);
+        }
+        catch (err) {
+            return { ...base, outcome: "moved", message: `Moved, but its keychain entry couldn't be deleted (${errorText(err)}).` };
+        }
+        await editConfig((fresh) => {
+            if (!fresh.keychainLogins?.[id])
+                return false;
+            const { [id]: _gone, ...rest } = fresh.keychainLogins;
+            fresh.keychainLogins = rest;
+        });
+    }
+    return { ...base, outcome: "moved" };
+}
+async function markMoveFailed(id) {
+    await editConfig((config) => {
+        const profile = config.profiles.find((p) => p.id === id);
+        if (!profile)
+            return false;
+        profile.moveFailedAt = new Date().toISOString();
+    }).catch(() => { });
+}
+/** Logins a move to the keychain should take: file logins, and F+ ones an old version rewrote. */
+const inFile = (p) => !p.secrets;
+/** Delete the session entries a move interrupted after its flip left behind (tagged, under the old key). */
+async function cleanLeftoverSessions(config) {
+    for (const profile of config.profiles) {
+        if (profile.secrets !== "keychain")
+            continue;
+        await removeTaggedSessions(profile.id, sessionKeyV2(profile.tenantUrl, profile.username)).catch(() => 0);
+    }
+}
+/**
+ * After a command, when the saved setting is `auto` or `keychain` (never the
+ * environment variable alone): move the file logins to the keychain, at most
+ * once a day for one that failed. `auto` stays quiet; `keychain` prints one
+ * line per failure. Never fails the command it follows.
+ */
+export async function runBackgroundMoves(warn = (line) => console.error(line)) {
+    try {
+        const config = await loadConfig();
+        await cleanLeftoverSessions(config);
+        const setting = config.secretStore;
+        if (setting !== "auto" && setting !== "keychain")
+            return;
+        const now = Date.now();
+        const due = config.profiles.filter((p) => inFile(p) && !(p.moveFailedAt && now - Date.parse(p.moveFailedAt) < RETRY_AFTER_MS));
+        if (!due.length)
+            return;
+        const problem = await keychainProblem();
+        if (problem) {
+            for (const profile of due)
+                await markMoveFailed(profile.id);
+            if (setting === "keychain")
+                warn(`WilmAI couldn't move saved passwords to the keychain: ${problem}. They stay in WilmAI's file for now.`);
+            return;
+        }
+        let moved = false;
+        for (const profile of due) {
+            const result = await moveLoginToKeychain(profile.id);
+            if (result.outcome === "moved")
+                moved = true;
+            if (result.outcome === "failed" && setting === "keychain")
+                warn(`WilmAI couldn't move the password for ${result.wilma} to the keychain: ${result.message}`);
+        }
+        if (moved)
+            await removeStrayTempFiles();
+    }
+    catch {
+        // A background move never fails the command it follows.
+    }
+}
+/**
+ * Remove temp files a crashed save left next to the config (they can hold the
+ * scrambled password). Only ones older than a minute: a save in progress in
+ * another process may still be using its own.
+ */
+export async function removeStrayTempFiles() {
+    const dir = dirname(getConfigPath());
+    const prefixes = [`${basename(getConfigPath())}.`, "wilmai-sessions.json."];
+    let removed = 0;
+    let names = [];
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return 0;
+    }
+    for (const name of names) {
+        if (!name.endsWith(".tmp") || !prefixes.some((prefix) => name.startsWith(prefix)))
+            continue;
+        const path = join(dir, name);
+        try {
+            if (Date.now() - (await stat(path)).mtimeMs < 60_000)
+                continue;
+            await rm(path, { force: true });
+            removed += 1;
+        }
+        catch {
+            // gone already
+        }
+    }
+    return removed;
+}
+/** Every login's place, for `wilma config secrets`. */
+export function whereSecretsAre(config) {
+    return config.profiles.map((p) => ({
+        ...describe(p),
+        store: p.secrets === "keychain" ? "keychain" : p.secrets ? "other" : "file",
+        hasTotp: p.secrets ? Boolean(p.hasTotp) : Boolean(p.totpSecretObfuscated),
+        ...(!p.secrets && config.keychainLogins?.[p.id] ? { keychainEntry: true } : {}),
+    }));
+}
+/**
+ * The keychain entries a config file names: `keychainLogins` values and
+ * `secretId`s. Read from the text itself, so a damaged file (`wilma config
+ * clear` is the way out of one) still gives the entries it names.
+ */
+export function entriesNamedIn(text) {
+    const entries = new Set();
+    try {
+        const config = JSON.parse(text);
+        for (const value of Object.values(config.keychainLogins ?? {}))
+            if (typeof value === "string")
+                entries.add(value);
+        for (const p of Array.isArray(config.profiles) ? config.profiles : [])
+            if (typeof p?.secretId === "string")
+                entries.add(p.secretId);
+    }
+    catch {
+        // Damaged: fall back to the entry ids written in it (32 hex characters as a value).
+    }
+    const block = /"keychainLogins"\s*:\s*\{([^}]*)/.exec(text)?.[1] ?? "";
+    for (const m of block.matchAll(/:\s*"([0-9a-f]{32})"/g))
+        entries.add(m[1]);
+    for (const m of text.matchAll(/"secretId"\s*:\s*"([0-9a-f]{32})"/g))
+        entries.add(m[1]);
+    return [...entries].filter((e) => /^[0-9a-f]{32}$/.test(e));
+}
+/** Delete the keychain entries the config file names (for `wilma config clear`); the ones that couldn't be deleted. */
+export async function deleteKnownEntries(configText) {
+    if (!configText)
+        return [];
+    const entries = entriesNamedIn(configText);
+    const failed = [];
+    for (const entry of entries) {
+        try {
+            await deleteLoginSecrets(entry);
+        }
+        catch {
+            failed.push(entry);
+        }
+    }
+    return failed;
+}

package/dist/secret-store.d.ts

@@ -0,0 +1,45 @@
+export declare const KEYCHAIN_SERVICE = "ai.wilm.wilma-cli";
+export declare const SECRET_STORE_SETTINGS: readonly ["file", "auto", "keychain"];
+export type SecretStoreSetting = (typeof SECRET_STORE_SETTINGS)[number];
+export type SecretErrorReason = "missing" | "refused" | "unavailable";
+export interface LoginSecrets {
+    password: string;
+    totpSecret?: string | null;
+}
+/** A keychain entry couldn't be read, written or deleted; `reason` says what the user can do. */
+export declare class SecretStoreError extends Error {
+    readonly reason: SecretErrorReason;
+    constructor(reason: SecretErrorReason, message: string, cause?: unknown);
+}
+/** The message a parent sees for each kind of failure (`wilma` names the Wilma when known). */
+export declare function secretErrorMessage(reason: SecretErrorReason, wilma?: string | null): string;
+/** The setting in effect: WILMAI_SECRET_STORE for this process, else the saved one, else the file. */
+export declare function effectiveSecretStore(saved: string | null | undefined, env?: NodeJS.ProcessEnv): SecretStoreSetting;
+export declare const newSecretId: () => string;
+export declare const newCredentialsStamp: () => string;
+/** null when the keychain can be used here (checked once per process); otherwise why not. */
+export declare function keychainProblem(): Promise<string | null>;
+/** Which keychain this process would use, for `wilma config secrets`. */
+export declare function keychainKind(): string;
+export interface SecretRef {
+    secretId: string;
+    credentialsStamp?: string | null;
+    /** The Wilma's name, for messages. */
+    wilma?: string | null;
+}
+/** A login's password and authenticator key from the keychain: read once per process, only when needed. */
+export declare function readLoginSecrets(ref: SecretRef): Promise<LoginSecrets>;
+/** Save a login's secrets in its keychain entry (replacing what was there). */
+export declare function writeLoginSecrets(secretId: string, secrets: LoginSecrets): Promise<void>;
+/**
+ * Read an entry straight from the keychain (no per-process memory), e.g. to
+ * check what was just written. A Windows read right after a write on another
+ * thread can briefly miss, so a miss is tried once more.
+ */
+export declare function readBackLoginSecrets(secretId: string): Promise<LoginSecrets | null>;
+/** Delete a login's keychain entry; true when there was one. */
+export declare function deleteLoginSecrets(secretId: string): Promise<boolean>;
+/** Whether a keychain call timed out and may still be running (the process should then exit when done). */
+export declare function abandonedKeychainCalls(): boolean;
+/** For tests in one process: forget what was read. */
+export declare function forgetSecretReads(): void;