@geminixiang/mikan 0.5.2 → 1.0.0-beta.0

package/dist/harness/session-store.js

@@ -0,0 +1,248 @@
+/**
+ * mikan-owned session storage.
+ *
+ * Sessions are append-only trees stored as JSONL files: a `session` header
+ * line followed by entries that carry `id`/`parentId` links. The format is
+ * the v3 layout mikan has always written, and entry shapes are structurally
+ * identical to pi-agent-core's `SessionTreeEntry`, so pi-agent-core's
+ * context-building and compaction helpers operate on these entries directly.
+ *
+ * The store is synchronous by design: every mikan call site (session scope
+ * resolution, chat-history sync, session view, admin portal) reads and
+ * writes sessions inside synchronous flows.
+ */
+import { randomUUID } from "crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "fs";
+import { dirname, resolve } from "path";
+import { buildSessionContext as buildContextFromEntries } from "@earendil-works/pi-agent-core";
+import { atomicWritePrivateFile } from "../utils/fs-atomic.js";
+import { CURRENT_SESSION_VERSION, } from "./types.js";
+/** Generate a unique short entry id (8 hex chars, collision-checked). */
+function generateEntryId(byId) {
+    for (let i = 0; i < 100; i++) {
+        const id = randomUUID().slice(0, 8);
+        if (!byId.has(id))
+            return id;
+    }
+    return randomUUID();
+}
+/** Parse JSONL content tolerantly: malformed lines are skipped. */
+export function parseSessionFileEntries(content) {
+    const entries = [];
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed &&
+                typeof parsed === "object" &&
+                typeof parsed.type === "string") {
+                entries.push(parsed);
+            }
+        }
+        catch {
+            // Skip malformed lines
+        }
+    }
+    return entries;
+}
+function isSessionHeader(entry) {
+    return entry.type === "session" && typeof entry.id === "string";
+}
+/**
+ * Load a session file. Returns no entries when the file is missing or its
+ * first parseable line is not a valid session header (mirrors the tolerant
+ * read behavior mikan has relied on). Throws only on I/O errors.
+ */
+export function loadSessionFileEntries(filePath) {
+    if (!existsSync(filePath))
+        return [];
+    const entries = parseSessionFileEntries(readFileSync(filePath, "utf-8"));
+    if (entries.length === 0)
+        return entries;
+    if (!isSessionHeader(entries[0]))
+        return [];
+    return entries;
+}
+/** True when the file exists and holds any non-whitespace content on disk. */
+function hasSessionFileContent(filePath) {
+    if (!existsSync(filePath))
+        return false;
+    return readFileSync(filePath, "utf-8").trim().length > 0;
+}
+/**
+ * Append-oriented session store over one v3 JSONL file.
+ *
+ * Reading is tolerant (missing files and malformed lines yield an empty
+ * session); appends persist immediately. A session opened from a file
+ * without a valid header gets its header materialized on the first append.
+ */
+export class SessionStore {
+    constructor(sessionFile, cwd, fileEntries) {
+        this.entries = [];
+        this.byId = new Map();
+        this.leafId = null;
+        this.sessionFile = resolve(sessionFile);
+        this.header = fileEntries.length > 0 && isSessionHeader(fileEntries[0]) ? fileEntries[0] : null;
+        this.headerOnDisk = this.header !== null;
+        this.sessionId = this.header?.id ?? randomUUID();
+        this.cwd = cwd;
+        for (const entry of fileEntries) {
+            if (isSessionHeader(entry))
+                continue;
+            if (entry.type === "leaf") {
+                // Written by pi-agent-core JSONL sessions; mikan tracks the leaf implicitly.
+                this.leafId = entry.targetId;
+                continue;
+            }
+            this.entries.push(entry);
+            this.byId.set(entry.id, entry);
+            this.leafId = entry.id;
+        }
+    }
+    /**
+     * Open a session file. A missing or empty file starts an empty session
+     * whose header is written on the first append. A file that has content but
+     * no leading session header is treated as corrupted and throws, rather than
+     * being silently overwritten on the next append (which would erase the
+     * existing history). Callers on read paths already wrap this in try/catch.
+     * @param cwdOverride Working directory override; defaults to the header cwd.
+     */
+    static open(path, cwdOverride) {
+        const fileEntries = loadSessionFileEntries(path);
+        if (fileEntries.length === 0 && hasSessionFileContent(path)) {
+            throw new Error(`Session file is corrupted (no valid session header): ${path}. ` +
+                `Refusing to open to avoid overwriting existing content.`);
+        }
+        const header = fileEntries.find(isSessionHeader);
+        const cwd = cwdOverride ?? header?.cwd ?? process.cwd();
+        return new SessionStore(path, cwd, fileEntries);
+    }
+    /** Create a new session file with a fresh header, replacing any existing file. */
+    static create(path, cwd, options) {
+        const header = {
+            type: "session",
+            version: CURRENT_SESSION_VERSION,
+            id: options?.id ?? randomUUID(),
+            timestamp: new Date().toISOString(),
+            cwd,
+        };
+        atomicWritePrivateFile(path, `${JSON.stringify(header)}\n`);
+        return new SessionStore(path, cwd, [header]);
+    }
+    getSessionFile() {
+        return this.sessionFile;
+    }
+    getCwd() {
+        return this.cwd;
+    }
+    /** Session header as read from disk, or null when the file had none. */
+    getHeader() {
+        return this.header;
+    }
+    /** Stable session id: the header id, or a generated id for fresh sessions. */
+    getSessionId() {
+        return this.sessionId;
+    }
+    getLeafId() {
+        return this.leafId;
+    }
+    getEntry(id) {
+        return this.byId.get(id);
+    }
+    /** All session entries (header excluded). Returns a shallow copy. */
+    getEntries() {
+        return [...this.entries];
+    }
+    /** Latest user-assigned session name, if any. */
+    getSessionName() {
+        for (let i = this.entries.length - 1; i >= 0; i--) {
+            const entry = this.entries[i];
+            if (entry.type === "session_info")
+                return entry.name?.trim() || undefined;
+        }
+        return undefined;
+    }
+    /**
+     * Walk from an entry to the root, returning entries in path order
+     * (root first). Defaults to the current leaf.
+     */
+    getBranch(fromId) {
+        const path = [];
+        let currentId = fromId ?? this.leafId;
+        while (currentId) {
+            const entry = this.byId.get(currentId);
+            if (!entry)
+                break;
+            path.push(entry);
+            currentId = entry.parentId;
+        }
+        return path.toReversed();
+    }
+    /**
+     * Build the LLM context (messages, thinking level, model) from the current
+     * branch, resolving compaction and branch summaries along the path.
+     */
+    buildSessionContext() {
+        return buildContextFromEntries(this.getBranch());
+    }
+    /** Append a chat message as a child of the current leaf. Returns the entry id. */
+    appendMessage(message) {
+        return this.appendEntry({ type: "message", message });
+    }
+    /** Append an extension/application data entry (never sent to the LLM). */
+    appendCustomEntry(customType, data) {
+        return this.appendEntry({ type: "custom", customType, data });
+    }
+    /** Append a custom message entry that participates in LLM context. */
+    appendCustomMessageEntry(customType, content, display, details) {
+        return this.appendEntry({ type: "custom_message", customType, content, display, details });
+    }
+    /** Record a user-visible session name. */
+    appendSessionInfo(name) {
+        return this.appendEntry({ type: "session_info", name });
+    }
+    /** Persist a compaction summary produced for this session. */
+    appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromHook) {
+        return this.appendEntry({
+            type: "compaction",
+            summary,
+            firstKeptEntryId,
+            tokensBefore,
+            ...(details !== undefined ? { details } : {}),
+            ...(fromHook !== undefined ? { fromHook } : {}),
+        });
+    }
+    appendEntry(partial) {
+        const entry = {
+            ...partial,
+            id: generateEntryId(this.byId),
+            parentId: this.leafId,
+            timestamp: new Date().toISOString(),
+        };
+        this.entries.push(entry);
+        this.byId.set(entry.id, entry);
+        this.leafId = entry.id;
+        this.persist(entry);
+        return entry.id;
+    }
+    persist(entry) {
+        if (!this.headerOnDisk) {
+            this.header ??= {
+                type: "session",
+                version: CURRENT_SESSION_VERSION,
+                id: this.sessionId,
+                timestamp: new Date().toISOString(),
+                cwd: this.cwd,
+            };
+            const lines = [this.header, ...this.entries].map((line) => JSON.stringify(line));
+            mkdirSync(dirname(this.sessionFile), { recursive: true });
+            atomicWritePrivateFile(this.sessionFile, `${lines.join("\n")}\n`);
+            this.headerOnDisk = true;
+            return;
+        }
+        appendFileSync(this.sessionFile, `${JSON.stringify(entry)}\n`);
+    }
+}
+//# sourceMappingURL=session-store.js.map

package/dist/harness/session-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-store.js","sourceRoot":"","sources":["../../src/harness/session-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AACzE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACxC,OAAO,EAAE,mBAAmB,IAAI,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAG/F,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EACL,uBAAuB,GAKxB,MAAM,YAAY,CAAC;AASpB,yEAAyE;AACzE,SAAS,eAAe,CAAC,IAA+B;IACtD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7B,MAAM,EAAE,GAAG,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,OAAO,EAAE,CAAC;IAC/B,CAAC;IACD,OAAO,UAAU,EAAE,CAAC;AACtB,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,uBAAuB,CAAC,OAAe;IACrD,MAAM,OAAO,GAAuB,EAAE,CAAC;IACvC,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,CAAC,OAAO;YAAE,SAAS;QACvB,IAAI,CAAC;YACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAC5C,IACE,MAAM;gBACN,OAAO,MAAM,KAAK,QAAQ;gBAC1B,OAAQ,MAA6B,CAAC,IAAI,KAAK,QAAQ,EACvD,CAAC;gBACD,OAAO,CAAC,IAAI,CAAC,MAA0B,CAAC,CAAC;YAC3C,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,uBAAuB;QACzB,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,eAAe,CAAC,KAAuB;IAC9C,OAAO,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,OAAQ,KAAuB,CAAC,EAAE,KAAK,QAAQ,CAAC;AACrF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,QAAgB;IACrD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,EAAE,CAAC;IACrC,MAAM,OAAO,GAAG,uBAAuB,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;IACzE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IACzC,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QAAE,OAAO,EAAE,CAAC;IAC5C,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,8EAA8E;AAC9E,SAAS,qBAAqB,CAAC,QAAgB;IAC7C,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,KAAK,CAAC;IACxC,OAAO,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,OAAO,YAAY;IAUvB,YAAoB,WAAmB,EAAE,GAAW,EAAE,WAA+B;QAJ7E,YAAO,GAAmB,EAAE,CAAC;QAC7B,SAAI,GAAG,IAAI,GAAG,EAAwB,CAAC;QACvC,WAAM,GAAkB,IAAI,CAAC;QAGnC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;QACxC,IAAI,CAAC,MAAM,GAAG,WAAW,CAAC,MAAM,GAAG,CAAC,IAAI,eAAe,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAChG,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC;QACzC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,MAAM,EAAE,EAAE,IAAI,UAAU,EAAE,CAAC;QACjD,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;YAChC,IAAI,eAAe,CAAC,KAAK,CAAC;gBAAE,SAAS;YACrC,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;gBAC1B,6EAA6E;gBAC7E,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAC;gBAC7B,SAAS;YACX,CAAC;YACD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACzB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;YAC/B,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,EAAE,CAAC;QACzB,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,IAAI,CAAC,IAAY,EAAE,WAAoB;QAC5C,MAAM,WAAW,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC;QACjD,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,IAAI,qBAAqB,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5D,MAAM,IAAI,KAAK,CACb,wDAAwD,IAAI,IAAI;gBAC9D,yDAAyD,CAC5D,CAAC;QACJ,CAAC;QACD,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;QACjD,MAAM,GAAG,GAAG,WAAW,IAAI,MAAM,EAAE,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;QACxD,OAAO,IAAI,YAAY,CAAC,IAAI,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC;IAClD,CAAC;IAED,kFAAkF;IAClF,MAAM,CAAC,MAAM,CAAC,IAAY,EAAE,GAAW,EAAE,OAAyB;QAChE,MAAM,MAAM,GAAkB;YAC5B,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,uBAAuB;YAChC,EAAE,EAAE,OAAO,EAAE,EAAE,IAAI,UAAU,EAAE;YAC/B,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,GAAG;SACJ,CAAC;QACF,sBAAsB,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC5D,OAAO,IAAI,YAAY,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAC/C,CAAC;IAED,cAAc;QACZ,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED,MAAM;QACJ,OAAO,IAAI,CAAC,GAAG,CAAC;IAClB,CAAC;IAED,wEAAwE;IACxE,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,8EAA8E;IAC9E,YAAY;QACV,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,QAAQ,CAAC,EAAU;QACjB,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC3B,CAAC;IAED,qEAAqE;IACrE,UAAU;QACR,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC;IAED,iDAAiD;IACjD,cAAc;QACZ,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAClD,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YAC9B,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc;gBAAE,OAAO,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;QAC5E,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;;OAGG;IACH,SAAS,CAAC,MAAe;QACvB,MAAM,IAAI,GAAmB,EAAE,CAAC;QAChC,IAAI,SAAS,GAAG,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC;QACtC,OAAO,SAAS,EAAE,CAAC;YACjB,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YACvC,IAAI,CAAC,KAAK;gBAAE,MAAM;YAClB,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACjB,SAAS,GAAG,KAAK,CAAC,QAAQ,CAAC;QAC7B,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACH,mBAAmB;QACjB,OAAO,uBAAuB,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;IACnD,CAAC;IAED,kFAAkF;IAClF,aAAa,CAAC,OAAqB;QACjC,OAAO,IAAI,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC;IACxD,CAAC;IAED,0EAA0E;IAC1E,iBAAiB,CAAC,UAAkB,EAAE,IAAc;QAClD,OAAO,IAAI,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;IAChE,CAAC;IAED,sEAAsE;IACtE,wBAAwB,CACtB,UAAkB,EAClB,OAAgD,EAChD,OAAgB,EAChB,OAAiB;QAEjB,OAAO,IAAI,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IAC7F,CAAC;IAED,0CAA0C;IAC1C,iBAAiB,CAAC,IAAY;QAC5B,OAAO,IAAI,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1D,CAAC;IAED,8DAA8D;IAC9D,gBAAgB,CACd,OAAe,EACf,gBAAwB,EACxB,YAAoB,EACpB,OAAiB,EACjB,QAAkB;QAElB,OAAO,IAAI,CAAC,WAAW,CAAC;YACtB,IAAI,EAAE,YAAY;YAClB,OAAO;YACP,gBAAgB;YAChB,YAAY;YACZ,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7C,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChD,CAAC,CAAC;IACL,CAAC;IAEO,WAAW,CAAC,OAA4B;QAC9C,MAAM,KAAK,GAAG;YACZ,GAAG,OAAO;YACV,EAAE,EAAE,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC;YAC9B,QAAQ,EAAE,IAAI,CAAC,MAAM;YACrB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpB,CAAC;QAClB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;QAC/B,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,EAAE,CAAC;QACvB,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACpB,OAAO,KAAK,CAAC,EAAE,CAAC;IAClB,CAAC;IAEO,OAAO,CAAC,KAAmB;QACjC,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACvB,IAAI,CAAC,MAAM,KAAK;gBACd,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,uBAAuB;gBAChC,EAAE,EAAE,IAAI,CAAC,SAAS;gBAClB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACnC,GAAG,EAAE,IAAI,CAAC,GAAG;aACd,CAAC;YACF,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;YACjF,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC1D,sBAAsB,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClE,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;YACzB,OAAO;QACT,CAAC;QACD,cAAc,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACjE,CAAC;CACF","sourcesContent":["/**\n * mikan-owned session storage.\n *\n * Sessions are append-only trees stored as JSONL files: a `session` header\n * line followed by entries that carry `id`/`parentId` links. The format is\n * the v3 layout mikan has always written, and entry shapes are structurally\n * identical to pi-agent-core's `SessionTreeEntry`, so pi-agent-core's\n * context-building and compaction helpers operate on these entries directly.\n *\n * The store is synchronous by design: every mikan call site (session scope\n * resolution, chat-history sync, session view, admin portal) reads and\n * writes sessions inside synchronous flows.\n */\nimport { randomUUID } from \"crypto\";\nimport { appendFileSync, existsSync, mkdirSync, readFileSync } from \"fs\";\nimport { dirname, resolve } from \"path\";\nimport { buildSessionContext as buildContextFromEntries } from \"@earendil-works/pi-agent-core\";\nimport type { AgentMessage } from \"@earendil-works/pi-agent-core\";\nimport type { ImageContent, TextContent } from \"@earendil-works/pi-ai\";\nimport { atomicWritePrivateFile } from \"../utils/fs-atomic.js\";\nimport {\n  CURRENT_SESSION_VERSION,\n  type SessionContext,\n  type SessionEntry,\n  type SessionFileEntry,\n  type SessionHeader,\n} from \"./types.js\";\n\n/** Distributive omit so each entry variant keeps its own fields. */\ntype PendingSessionEntry = SessionEntry extends infer TEntry\n  ? TEntry extends SessionEntry\n    ? Omit<TEntry, \"id\" | \"parentId\" | \"timestamp\">\n    : never\n  : never;\n\n/** Generate a unique short entry id (8 hex chars, collision-checked). */\nfunction generateEntryId(byId: Map<string, SessionEntry>): string {\n  for (let i = 0; i < 100; i++) {\n    const id = randomUUID().slice(0, 8);\n    if (!byId.has(id)) return id;\n  }\n  return randomUUID();\n}\n\n/** Parse JSONL content tolerantly: malformed lines are skipped. */\nexport function parseSessionFileEntries(content: string): SessionFileEntry[] {\n  const entries: SessionFileEntry[] = [];\n  for (const line of content.split(\"\\n\")) {\n    const trimmed = line.trim();\n    if (!trimmed) continue;\n    try {\n      const parsed: unknown = JSON.parse(trimmed);\n      if (\n        parsed &&\n        typeof parsed === \"object\" &&\n        typeof (parsed as { type?: unknown }).type === \"string\"\n      ) {\n        entries.push(parsed as SessionFileEntry);\n      }\n    } catch {\n      // Skip malformed lines\n    }\n  }\n  return entries;\n}\n\nfunction isSessionHeader(entry: SessionFileEntry): entry is SessionHeader {\n  return entry.type === \"session\" && typeof (entry as SessionHeader).id === \"string\";\n}\n\n/**\n * Load a session file. Returns no entries when the file is missing or its\n * first parseable line is not a valid session header (mirrors the tolerant\n * read behavior mikan has relied on). Throws only on I/O errors.\n */\nexport function loadSessionFileEntries(filePath: string): SessionFileEntry[] {\n  if (!existsSync(filePath)) return [];\n  const entries = parseSessionFileEntries(readFileSync(filePath, \"utf-8\"));\n  if (entries.length === 0) return entries;\n  if (!isSessionHeader(entries[0])) return [];\n  return entries;\n}\n\n/** True when the file exists and holds any non-whitespace content on disk. */\nfunction hasSessionFileContent(filePath: string): boolean {\n  if (!existsSync(filePath)) return false;\n  return readFileSync(filePath, \"utf-8\").trim().length > 0;\n}\n\n/**\n * Append-oriented session store over one v3 JSONL file.\n *\n * Reading is tolerant (missing files and malformed lines yield an empty\n * session); appends persist immediately. A session opened from a file\n * without a valid header gets its header materialized on the first append.\n */\nexport class SessionStore {\n  private readonly sessionFile: string;\n  private readonly cwd: string;\n  private readonly sessionId: string;\n  private header: SessionHeader | null;\n  private headerOnDisk: boolean;\n  private entries: SessionEntry[] = [];\n  private byId = new Map<string, SessionEntry>();\n  private leafId: string | null = null;\n\n  private constructor(sessionFile: string, cwd: string, fileEntries: SessionFileEntry[]) {\n    this.sessionFile = resolve(sessionFile);\n    this.header = fileEntries.length > 0 && isSessionHeader(fileEntries[0]) ? fileEntries[0] : null;\n    this.headerOnDisk = this.header !== null;\n    this.sessionId = this.header?.id ?? randomUUID();\n    this.cwd = cwd;\n    for (const entry of fileEntries) {\n      if (isSessionHeader(entry)) continue;\n      if (entry.type === \"leaf\") {\n        // Written by pi-agent-core JSONL sessions; mikan tracks the leaf implicitly.\n        this.leafId = entry.targetId;\n        continue;\n      }\n      this.entries.push(entry);\n      this.byId.set(entry.id, entry);\n      this.leafId = entry.id;\n    }\n  }\n\n  /**\n   * Open a session file. A missing or empty file starts an empty session\n   * whose header is written on the first append. A file that has content but\n   * no leading session header is treated as corrupted and throws, rather than\n   * being silently overwritten on the next append (which would erase the\n   * existing history). Callers on read paths already wrap this in try/catch.\n   * @param cwdOverride Working directory override; defaults to the header cwd.\n   */\n  static open(path: string, cwdOverride?: string): SessionStore {\n    const fileEntries = loadSessionFileEntries(path);\n    if (fileEntries.length === 0 && hasSessionFileContent(path)) {\n      throw new Error(\n        `Session file is corrupted (no valid session header): ${path}. ` +\n          `Refusing to open to avoid overwriting existing content.`,\n      );\n    }\n    const header = fileEntries.find(isSessionHeader);\n    const cwd = cwdOverride ?? header?.cwd ?? process.cwd();\n    return new SessionStore(path, cwd, fileEntries);\n  }\n\n  /** Create a new session file with a fresh header, replacing any existing file. */\n  static create(path: string, cwd: string, options?: { id?: string }): SessionStore {\n    const header: SessionHeader = {\n      type: \"session\",\n      version: CURRENT_SESSION_VERSION,\n      id: options?.id ?? randomUUID(),\n      timestamp: new Date().toISOString(),\n      cwd,\n    };\n    atomicWritePrivateFile(path, `${JSON.stringify(header)}\\n`);\n    return new SessionStore(path, cwd, [header]);\n  }\n\n  getSessionFile(): string {\n    return this.sessionFile;\n  }\n\n  getCwd(): string {\n    return this.cwd;\n  }\n\n  /** Session header as read from disk, or null when the file had none. */\n  getHeader(): SessionHeader | null {\n    return this.header;\n  }\n\n  /** Stable session id: the header id, or a generated id for fresh sessions. */\n  getSessionId(): string {\n    return this.sessionId;\n  }\n\n  getLeafId(): string | null {\n    return this.leafId;\n  }\n\n  getEntry(id: string): SessionEntry | undefined {\n    return this.byId.get(id);\n  }\n\n  /** All session entries (header excluded). Returns a shallow copy. */\n  getEntries(): SessionEntry[] {\n    return [...this.entries];\n  }\n\n  /** Latest user-assigned session name, if any. */\n  getSessionName(): string | undefined {\n    for (let i = this.entries.length - 1; i >= 0; i--) {\n      const entry = this.entries[i];\n      if (entry.type === \"session_info\") return entry.name?.trim() || undefined;\n    }\n    return undefined;\n  }\n\n  /**\n   * Walk from an entry to the root, returning entries in path order\n   * (root first). Defaults to the current leaf.\n   */\n  getBranch(fromId?: string): SessionEntry[] {\n    const path: SessionEntry[] = [];\n    let currentId = fromId ?? this.leafId;\n    while (currentId) {\n      const entry = this.byId.get(currentId);\n      if (!entry) break;\n      path.push(entry);\n      currentId = entry.parentId;\n    }\n    return path.toReversed();\n  }\n\n  /**\n   * Build the LLM context (messages, thinking level, model) from the current\n   * branch, resolving compaction and branch summaries along the path.\n   */\n  buildSessionContext(): SessionContext {\n    return buildContextFromEntries(this.getBranch());\n  }\n\n  /** Append a chat message as a child of the current leaf. Returns the entry id. */\n  appendMessage(message: AgentMessage): string {\n    return this.appendEntry({ type: \"message\", message });\n  }\n\n  /** Append an extension/application data entry (never sent to the LLM). */\n  appendCustomEntry(customType: string, data?: unknown): string {\n    return this.appendEntry({ type: \"custom\", customType, data });\n  }\n\n  /** Append a custom message entry that participates in LLM context. */\n  appendCustomMessageEntry(\n    customType: string,\n    content: string | (TextContent | ImageContent)[],\n    display: boolean,\n    details?: unknown,\n  ): string {\n    return this.appendEntry({ type: \"custom_message\", customType, content, display, details });\n  }\n\n  /** Record a user-visible session name. */\n  appendSessionInfo(name: string): string {\n    return this.appendEntry({ type: \"session_info\", name });\n  }\n\n  /** Persist a compaction summary produced for this session. */\n  appendCompaction(\n    summary: string,\n    firstKeptEntryId: string,\n    tokensBefore: number,\n    details?: unknown,\n    fromHook?: boolean,\n  ): string {\n    return this.appendEntry({\n      type: \"compaction\",\n      summary,\n      firstKeptEntryId,\n      tokensBefore,\n      ...(details !== undefined ? { details } : {}),\n      ...(fromHook !== undefined ? { fromHook } : {}),\n    });\n  }\n\n  private appendEntry(partial: PendingSessionEntry): string {\n    const entry = {\n      ...partial,\n      id: generateEntryId(this.byId),\n      parentId: this.leafId,\n      timestamp: new Date().toISOString(),\n    } as SessionEntry;\n    this.entries.push(entry);\n    this.byId.set(entry.id, entry);\n    this.leafId = entry.id;\n    this.persist(entry);\n    return entry.id;\n  }\n\n  private persist(entry: SessionEntry): void {\n    if (!this.headerOnDisk) {\n      this.header ??= {\n        type: \"session\",\n        version: CURRENT_SESSION_VERSION,\n        id: this.sessionId,\n        timestamp: new Date().toISOString(),\n        cwd: this.cwd,\n      };\n      const lines = [this.header, ...this.entries].map((line) => JSON.stringify(line));\n      mkdirSync(dirname(this.sessionFile), { recursive: true });\n      atomicWritePrivateFile(this.sessionFile, `${lines.join(\"\\n\")}\\n`);\n      this.headerOnDisk = true;\n      return;\n    }\n    appendFileSync(this.sessionFile, `${JSON.stringify(entry)}\\n`);\n  }\n}\n"]}

package/dist/harness/settings.d.ts

@@ -0,0 +1,47 @@
+import type { CompactionSettings } from "@earendil-works/pi-agent-core";
+export type { CompactionSettings };
+export interface RetrySettings {
+    enabled: boolean;
+    maxRetries: number;
+    baseDelayMs: number;
+}
+export declare const DEFAULT_RETRY_SETTINGS: RetrySettings;
+/**
+ * Per-run resource ceilings — the harness's external circuit breakers.
+ *
+ * An LLM cannot reliably decide on its own when to stop (the halting problem),
+ * so a runaway run has to be stopped from the outside. When any populated cap
+ * is exceeded, the run is aborted and a `budget_exceeded` event is emitted.
+ * Every field is a cap on a single `prompt()` call; an undefined field means
+ * "no cap on that axis". Interactive runs are gated turn-by-turn by a human,
+ * so they default to uncapped; autonomous runs (scheduled events, triggers)
+ * pass {@link DEFAULT_EVENT_BUDGET}, where nobody is watching the loop.
+ */
+export interface BudgetSettings {
+    /** Max cumulative tokens processed this run (input + output + cache read/write). */
+    maxTokens?: number;
+    /** Max cumulative provider cost (USD) this run. Requires a populated model cost table. */
+    maxCostUsd?: number;
+    /** Max wall-clock duration for the run, in milliseconds. */
+    maxDurationMs?: number;
+    /** Max number of LLM calls (assistant turns) this run. */
+    maxLlmCalls?: number;
+}
+/** Interactive runs are human-gated per turn — no automatic ceiling by default. */
+export declare const DEFAULT_BUDGET_SETTINGS: BudgetSettings;
+/**
+ * Ceiling for autonomous (event / trigger) runs, where no human is watching
+ * the loop. Deliberately generous — it is a stop-loss, not a target.
+ */
+export declare const DEFAULT_EVENT_BUDGET: BudgetSettings;
+export interface HarnessSettings {
+    compaction: CompactionSettings;
+    retry: RetrySettings;
+    budget: BudgetSettings;
+}
+export declare function resolveHarnessSettings(overrides?: {
+    compaction?: Partial<CompactionSettings>;
+    retry?: Partial<RetrySettings>;
+    budget?: Partial<BudgetSettings>;
+}): HarnessSettings;
+//# sourceMappingURL=settings.d.ts.map

package/dist/harness/settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../src/harness/settings.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAExE,YAAY,EAAE,kBAAkB,EAAE,CAAC;AAEnC,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,sBAAsB,EAAE,aAIpC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B,oFAAoF;IACpF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0FAA0F;IAC1F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,mFAAmF;AACnF,eAAO,MAAM,uBAAuB,EAAE,cAAmB,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,cAIlC,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,kBAAkB,CAAC;IAC/B,KAAK,EAAE,aAAa,CAAC;IACrB,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,wBAAgB,sBAAsB,CAAC,SAAS,CAAC,EAAE;IACjD,UAAU,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACzC,KAAK,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;CAClC,GAAG,eAAe,CAMlB"}

package/dist/harness/settings.js

@@ -0,0 +1,29 @@
+/**
+ * Runtime settings for the mikan harness. mikan runs headless, so these are
+ * plain values with defaults matching the behavior mikan shipped with.
+ */
+import { DEFAULT_COMPACTION_SETTINGS } from "@earendil-works/pi-agent-core";
+export const DEFAULT_RETRY_SETTINGS = {
+    enabled: true,
+    maxRetries: 3,
+    baseDelayMs: 2000,
+};
+/** Interactive runs are human-gated per turn — no automatic ceiling by default. */
+export const DEFAULT_BUDGET_SETTINGS = {};
+/**
+ * Ceiling for autonomous (event / trigger) runs, where no human is watching
+ * the loop. Deliberately generous — it is a stop-loss, not a target.
+ */
+export const DEFAULT_EVENT_BUDGET = {
+    maxDurationMs: 10 * 60 * 1000,
+    maxLlmCalls: 50,
+    maxCostUsd: 2,
+};
+export function resolveHarnessSettings(overrides) {
+    return {
+        compaction: { ...DEFAULT_COMPACTION_SETTINGS, ...overrides?.compaction },
+        retry: { ...DEFAULT_RETRY_SETTINGS, ...overrides?.retry },
+        budget: { ...DEFAULT_BUDGET_SETTINGS, ...overrides?.budget },
+    };
+}
+//# sourceMappingURL=settings.js.map

package/dist/harness/settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.js","sourceRoot":"","sources":["../../src/harness/settings.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAW5E,MAAM,CAAC,MAAM,sBAAsB,GAAkB;IACnD,OAAO,EAAE,IAAI;IACb,UAAU,EAAE,CAAC;IACb,WAAW,EAAE,IAAI;CAClB,CAAC;AAwBF,mFAAmF;AACnF,MAAM,CAAC,MAAM,uBAAuB,GAAmB,EAAE,CAAC;AAE1D;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAmB;IAClD,aAAa,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI;IAC7B,WAAW,EAAE,EAAE;IACf,UAAU,EAAE,CAAC;CACd,CAAC;AAQF,MAAM,UAAU,sBAAsB,CAAC,SAItC;IACC,OAAO;QACL,UAAU,EAAE,EAAE,GAAG,2BAA2B,EAAE,GAAG,SAAS,EAAE,UAAU,EAAE;QACxE,KAAK,EAAE,EAAE,GAAG,sBAAsB,EAAE,GAAG,SAAS,EAAE,KAAK,EAAE;QACzD,MAAM,EAAE,EAAE,GAAG,uBAAuB,EAAE,GAAG,SAAS,EAAE,MAAM,EAAE;KAC7D,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Runtime settings for the mikan harness. mikan runs headless, so these are\n * plain values with defaults matching the behavior mikan shipped with.\n */\nimport { DEFAULT_COMPACTION_SETTINGS } from \"@earendil-works/pi-agent-core\";\nimport type { CompactionSettings } from \"@earendil-works/pi-agent-core\";\n\nexport type { CompactionSettings };\n\nexport interface RetrySettings {\n  enabled: boolean;\n  maxRetries: number;\n  baseDelayMs: number;\n}\n\nexport const DEFAULT_RETRY_SETTINGS: RetrySettings = {\n  enabled: true,\n  maxRetries: 3,\n  baseDelayMs: 2000,\n};\n\n/**\n * Per-run resource ceilings — the harness's external circuit breakers.\n *\n * An LLM cannot reliably decide on its own when to stop (the halting problem),\n * so a runaway run has to be stopped from the outside. When any populated cap\n * is exceeded, the run is aborted and a `budget_exceeded` event is emitted.\n * Every field is a cap on a single `prompt()` call; an undefined field means\n * \"no cap on that axis\". Interactive runs are gated turn-by-turn by a human,\n * so they default to uncapped; autonomous runs (scheduled events, triggers)\n * pass {@link DEFAULT_EVENT_BUDGET}, where nobody is watching the loop.\n */\nexport interface BudgetSettings {\n  /** Max cumulative tokens processed this run (input + output + cache read/write). */\n  maxTokens?: number;\n  /** Max cumulative provider cost (USD) this run. Requires a populated model cost table. */\n  maxCostUsd?: number;\n  /** Max wall-clock duration for the run, in milliseconds. */\n  maxDurationMs?: number;\n  /** Max number of LLM calls (assistant turns) this run. */\n  maxLlmCalls?: number;\n}\n\n/** Interactive runs are human-gated per turn — no automatic ceiling by default. */\nexport const DEFAULT_BUDGET_SETTINGS: BudgetSettings = {};\n\n/**\n * Ceiling for autonomous (event / trigger) runs, where no human is watching\n * the loop. Deliberately generous — it is a stop-loss, not a target.\n */\nexport const DEFAULT_EVENT_BUDGET: BudgetSettings = {\n  maxDurationMs: 10 * 60 * 1000,\n  maxLlmCalls: 50,\n  maxCostUsd: 2,\n};\n\nexport interface HarnessSettings {\n  compaction: CompactionSettings;\n  retry: RetrySettings;\n  budget: BudgetSettings;\n}\n\nexport function resolveHarnessSettings(overrides?: {\n  compaction?: Partial<CompactionSettings>;\n  retry?: Partial<RetrySettings>;\n  budget?: Partial<BudgetSettings>;\n}): HarnessSettings {\n  return {\n    compaction: { ...DEFAULT_COMPACTION_SETTINGS, ...overrides?.compaction },\n    retry: { ...DEFAULT_RETRY_SETTINGS, ...overrides?.retry },\n    budget: { ...DEFAULT_BUDGET_SETTINGS, ...overrides?.budget },\n  };\n}\n"]}

package/dist/harness/skills.d.ts

@@ -0,0 +1,54 @@
+/** A loaded skill. `baseDir` is the directory containing the skill file. */
+export interface MikanSkill {
+    name: string;
+    description: string;
+    /** Full skill instructions (file content without frontmatter). */
+    content: string;
+    filePath: string;
+    baseDir: string;
+    /** Where the skill was loaded from (e.g. "workspace", "channel"). */
+    source: string;
+    /** Exclude from model-visible skill lists. */
+    disableModelInvocation?: boolean;
+    /**
+     * Embed the skill body in the prompt instead of referencing its file path.
+     * Used for skills whose files the agent cannot read at runtime (e.g.
+     * extension skills under the host-only state dir in sandbox modes).
+     */
+    inline?: boolean;
+}
+export interface SkillDiagnostic {
+    type: "warning";
+    message: string;
+    path: string;
+}
+export interface LoadSkillsResult {
+    skills: MikanSkill[];
+    diagnostics: SkillDiagnostic[];
+}
+interface Frontmatter {
+    values: Record<string, string>;
+    body: string;
+}
+/**
+ * Parse simple `key: value` YAML frontmatter delimited by `---` lines.
+ * Quoted values are unquoted; nested structures are not supported.
+ */
+export declare function parseFrontmatter(content: string): Frontmatter;
+/**
+ * Load skills from a directory tree.
+ * - A directory containing `SKILL.md` is a skill root; no further recursion.
+ * - Direct `.md` children of the top-level directory load as skills.
+ * - Dot-directories and `node_modules` are skipped.
+ */
+export declare function loadSkillsFromDir(options: {
+    dir: string;
+    source: string;
+}): LoadSkillsResult;
+/**
+ * Format skills for a system prompt using the Agent Skills XML block.
+ * Skills with `disableModelInvocation` are excluded.
+ */
+export declare function formatSkillsForPrompt(skills: MikanSkill[]): string;
+export {};
+//# sourceMappingURL=skills.d.ts.map

package/dist/harness/skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/harness/skills.ts"],"names":[],"mappings":"AAeA,4EAA4E;AAC5E,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,WAAW,EAAE,eAAe,EAAE,CAAC;CAChC;AAED,UAAU,WAAW;IACnB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,CAoB7D;AAkED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,gBAAgB,CAE5F;AAgFD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,CAyBlE"}

package/dist/harness/skills.js

@@ -0,0 +1,203 @@
+/**
+ * Skill loading for the mikan harness.
+ *
+ * Skills follow the Agent Skills layout: a directory containing a `SKILL.md`
+ * with YAML frontmatter (`name`, `description`), or standalone `.md` files in
+ * the root of a skills directory. Discovery mirrors the behavior mikan's
+ * system prompt documents: a directory with a `SKILL.md` is a skill root
+ * (no further recursion), other directories are traversed.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "fs";
+import { basename, dirname, join } from "path";
+const MAX_NAME_LENGTH = 64;
+const MAX_DESCRIPTION_LENGTH = 1024;
+/**
+ * Parse simple `key: value` YAML frontmatter delimited by `---` lines.
+ * Quoted values are unquoted; nested structures are not supported.
+ */
+export function parseFrontmatter(content) {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+    if (!match)
+        return { values: {}, body: content };
+    const values = {};
+    for (const line of match[1].split(/\r?\n/)) {
+        const separator = line.indexOf(":");
+        if (separator === -1)
+            continue;
+        const key = line.slice(0, separator).trim();
+        if (!key)
+            continue;
+        let value = line.slice(separator + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        values[key] = value;
+    }
+    return { values, body: content.slice(match[0].length) };
+}
+function validateSkill(name, description) {
+    const errors = [];
+    if (name.length > MAX_NAME_LENGTH) {
+        errors.push(`name exceeds ${MAX_NAME_LENGTH} characters (${name.length})`);
+    }
+    if (!/^[a-z0-9-]+$/.test(name) ||
+        name.startsWith("-") ||
+        name.endsWith("-") ||
+        name.includes("--")) {
+        errors.push("name must be lowercase a-z, 0-9 and single hyphens, not at the edges");
+    }
+    if (description.length > MAX_DESCRIPTION_LENGTH) {
+        errors.push(`description exceeds ${MAX_DESCRIPTION_LENGTH} characters (${description.length})`);
+    }
+    return errors;
+}
+function loadSkillFromFile(filePath, source) {
+    const diagnostics = [];
+    try {
+        const raw = readFileSync(filePath, "utf-8");
+        const { values, body } = parseFrontmatter(raw);
+        const skillDir = dirname(filePath);
+        const name = values.name || basename(skillDir);
+        const description = values.description ?? "";
+        if (!description.trim()) {
+            diagnostics.push({ type: "warning", message: "description is required", path: filePath });
+            return { skill: null, diagnostics };
+        }
+        for (const error of validateSkill(name, description)) {
+            diagnostics.push({ type: "warning", message: error, path: filePath });
+        }
+        return {
+            skill: {
+                name,
+                description,
+                content: body.trim(),
+                filePath,
+                baseDir: skillDir,
+                source,
+                disableModelInvocation: values["disable-model-invocation"] === "true",
+            },
+            diagnostics,
+        };
+    }
+    catch (error) {
+        diagnostics.push({
+            type: "warning",
+            message: error instanceof Error ? error.message : "failed to parse skill file",
+            path: filePath,
+        });
+        return { skill: null, diagnostics };
+    }
+}
+/**
+ * Load skills from a directory tree.
+ * - A directory containing `SKILL.md` is a skill root; no further recursion.
+ * - Direct `.md` children of the top-level directory load as skills.
+ * - Dot-directories and `node_modules` are skipped.
+ */
+export function loadSkillsFromDir(options) {
+    return loadSkillsFromDirInternal(options.dir, options.source, true);
+}
+function loadSkillsFromDirInternal(dir, source, includeRootFiles) {
+    const skills = [];
+    const diagnostics = [];
+    if (!existsSync(dir))
+        return { skills, diagnostics };
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return { skills, diagnostics };
+    }
+    const skillFile = entries.find((entry) => entry.name === "SKILL.md" && isFileLike(dir, entry));
+    if (skillFile) {
+        const result = loadSkillFromFile(join(dir, skillFile.name), source);
+        if (result.skill)
+            skills.push(result.skill);
+        diagnostics.push(...result.diagnostics);
+        return { skills, diagnostics };
+    }
+    for (const entry of entries) {
+        if (entry.name.startsWith(".") || entry.name === "node_modules")
+            continue;
+        const fullPath = join(dir, entry.name);
+        if (isDirectoryLike(dir, entry)) {
+            const subResult = loadSkillsFromDirInternal(fullPath, source, false);
+            skills.push(...subResult.skills);
+            diagnostics.push(...subResult.diagnostics);
+            continue;
+        }
+        if (!includeRootFiles || !entry.name.endsWith(".md") || !isFileLike(dir, entry))
+            continue;
+        const result = loadSkillFromFile(fullPath, source);
+        if (result.skill)
+            skills.push(result.skill);
+        diagnostics.push(...result.diagnostics);
+    }
+    return { skills, diagnostics };
+}
+function isFileLike(dir, entry) {
+    if (entry.isFile())
+        return true;
+    if (!entry.isSymbolicLink())
+        return false;
+    try {
+        return statSync(join(dir, entry.name)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function isDirectoryLike(dir, entry) {
+    if (entry.isDirectory())
+        return true;
+    if (!entry.isSymbolicLink())
+        return false;
+    try {
+        return statSync(join(dir, entry.name)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function escapeXml(str) {
+    return str
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+/**
+ * Format skills for a system prompt using the Agent Skills XML block.
+ * Skills with `disableModelInvocation` are excluded.
+ */
+export function formatSkillsForPrompt(skills) {
+    const visible = skills.filter((skill) => !skill.disableModelInvocation);
+    if (visible.length === 0)
+        return "";
+    const lines = [
+        "\n\nThe following skills provide specialized instructions for specific tasks.",
+        "Use the read tool to load a skill's file when the task matches its description.",
+        "When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool commands.",
+        "",
+        "<available_skills>",
+    ];
+    for (const skill of visible) {
+        lines.push("  <skill>");
+        lines.push(`    <name>${escapeXml(skill.name)}</name>`);
+        lines.push(`    <description>${escapeXml(skill.description)}</description>`);
+        if (skill.inline) {
+            // Inline skills carry their body: the agent cannot read their file.
+            lines.push(`    <instructions>${escapeXml(skill.content)}</instructions>`);
+        }
+        else {
+            lines.push(`    <location>${escapeXml(skill.filePath)}</location>`);
+        }
+        lines.push("  </skill>");
+    }
+    lines.push("</available_skills>");
+    return lines.join("\n");
+}
+//# sourceMappingURL=skills.js.map