@caupulican/pi-adaptative 0.86.17 → 0.90.2

package/dist/core/session-role.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-role.js","sourceRoot":"","sources":["../../src/core/session-role.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAKrE,MAAM,CAAC,MAAM,mBAAmB,GAAG,iBAAiB,CAAC;AAErD,MAAM,UAAU,qBAAqB,CAAC,KAAa;IAClD,OAAO,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,QAAQ,CAAC;AAC/C,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,sBAAsB,CAAC,IAAyB,EAAE,GAAG,GAAsB,OAAO,CAAC,GAAG;IACrG,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACvB,GAAG,CAAC,mBAAmB,CAAC,GAAG,QAAQ,CAAC;IACrC,CAAC;SAAM,IAAI,GAAG,CAAC,mBAAmB,CAAC,KAAK,QAAQ,EAAE,CAAC;QAClD,GAAG,CAAC,mBAAmB,CAAC,GAAG,MAAM,CAAC;IACnC,CAAC;AACF,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,cAAc,CAAC,GAAG,GAAsB,OAAO,CAAC,GAAG;IAClE,IAAI,GAAG,CAAC,mBAAmB,CAAC,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC3D,IAAI,YAAY,CAAC,GAAG,CAAC,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IACrD,IAAI,uBAAuB,CAAC,GAAG,CAAC,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IAChE,OAAO,MAAM,CAAC;AACf,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,eAAe,CAAC,GAAG,GAAsB,OAAO,CAAC,GAAG;IACnE,OAAO,cAAc,CAAC,GAAG,CAAC,KAAK,QAAQ,CAAC;AACzC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAwB,IAAI,GAAG,CAAC;IAClE,MAAM;IACN,cAAc;IACd,cAAc;IACd,UAAU;IACV,iBAAiB;IACjB,gBAAgB;IAChB,kBAAkB;IAClB,cAAc;IACd,UAAU;IACV,oBAAoB;IACpB,eAAe;IACf,oBAAoB;IACpB,eAAe;IACf,QAAQ;CACR,CAAC,CAAC","sourcesContent":["/**\n * Session-role identity: distinguishes a MAIN session (an interactive/direct `pi` session) from a\n * WORKER session (lane-bound or explicitly dispatched) — the seam every worker-scoped UAC ceiling\n * and zero-footprint store gates on (see runtime-builder.ts's `isAllowedTool`, the worktree_sync\n * tool's worker scoping, and the read-only store options threaded through the persistence layer).\n *\n * A session is a worker iff EITHER:\n * - `PI_SESSION_ROLE=worker` is set (an explicit launcher declaration),\n * - a valid `PI_PARENT_PID` declares this process as a managed child, or\n * - it is bound to a worktree-sync lane (`PI_WORKTREE_LANE`; see worktree-sync/runtime.ts) — a\n *   lane-bound session is a worker by construction, regardless of how it was launched.\n *\n * `PI_SESSION_ROLE=main` is deliberately NOT an escalation: it can never override a bound lane.\n * There is no environment value a lane-bound process can set to shed the worker ceiling — the env\n * var is additive evidence for \"worker\", never a downgrade signal.\n */\n\nimport { getParentPid } from \"./process-identity.ts\";\nimport { getBoundWorktreeLaneKey } from \"./worktree-sync/runtime.ts\";\n\nexport type SessionRole = \"main\" | \"worker\";\nexport type TerminalSessionMode = \"user\" | \"worker\";\n\nexport const PI_SESSION_ROLE_ENV = \"PI_SESSION_ROLE\";\n\nexport function isTerminalSessionMode(value: string): value is TerminalSessionMode {\n\treturn value === \"user\" || value === \"worker\";\n}\n\n/** Apply the terminal audience declaration without bypassing worker inference or UAC ceilings. */\nexport function setTerminalSessionMode(mode: TerminalSessionMode, env: NodeJS.ProcessEnv = process.env): void {\n\tif (mode === \"worker\") {\n\t\tenv[PI_SESSION_ROLE_ENV] = \"worker\";\n\t} else if (env[PI_SESSION_ROLE_ENV] !== \"worker\") {\n\t\tenv[PI_SESSION_ROLE_ENV] = \"main\";\n\t}\n}\n\n/** Derive this process's session role from the environment (env-injectable for tests). */\nexport function getSessionRole(env: NodeJS.ProcessEnv = process.env): SessionRole {\n\tif (env[PI_SESSION_ROLE_ENV] === \"worker\") return \"worker\";\n\tif (getParentPid(env) !== undefined) return \"worker\";\n\tif (getBoundWorktreeLaneKey(env) !== undefined) return \"worker\";\n\treturn \"main\";\n}\n\n/** True iff this process is a worker session (lane-bound or explicitly declared). */\nexport function isWorkerSession(env: NodeJS.ProcessEnv = process.env): boolean {\n\treturn getSessionRole(env) === \"worker\";\n}\n\n/**\n * Tools a worker session may never activate: the orchestration/self-adaptation surface that would\n * let a worker spawn its own sub-orchestration, bypass its parent to request owner input, mutate\n * settings-driven learning/model state, or shell out to the unbounded `python` execution contract.\n * `python` is load-bearing for the zero-footprint guarantee (it can write anywhere the interpreter\n * can reach); `context_scout` is\n * sub-orchestration (spawns its own isolated agent loop). `bash` is deliberately NOT included: it\n * stays available as the documented cooperative boundary (see docs/worktree-sync.md) — the same\n * trust model the lane gate already applies to foreign CLIs it cannot structurally contain.\n */\nexport const WORKER_FORBIDDEN_TOOLS: ReadonlySet<string> = new Set([\n\t\"goal\",\n\t\"ask_question\",\n\t\"secret_store\",\n\t\"delegate\",\n\t\"delegate_status\",\n\t\"profile_writer\",\n\t\"improvement_loop\",\n\t\"extensionify\",\n\t\"skillify\",\n\t\"run_toolkit_script\",\n\t\"model_fitness\",\n\t\"tmux_agent_manager\",\n\t\"context_scout\",\n\t\"python\",\n]);\n"]}
+{"version":3,"file":"session-role.js","sourceRoot":"","sources":["../../src/core/session-role.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAKrE,MAAM,CAAC,MAAM,mBAAmB,GAAG,iBAAiB,CAAC;AAErD,MAAM,UAAU,qBAAqB,CAAC,KAAa;IAClD,OAAO,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,QAAQ,CAAC;AAC/C,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,sBAAsB,CAAC,IAAyB,EAAE,GAAG,GAAsB,OAAO,CAAC,GAAG;IACrG,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACvB,GAAG,CAAC,mBAAmB,CAAC,GAAG,QAAQ,CAAC;IACrC,CAAC;SAAM,IAAI,GAAG,CAAC,mBAAmB,CAAC,KAAK,QAAQ,EAAE,CAAC;QAClD,GAAG,CAAC,mBAAmB,CAAC,GAAG,MAAM,CAAC;IACnC,CAAC;AACF,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,cAAc,CAAC,GAAG,GAAsB,OAAO,CAAC,GAAG;IAClE,IAAI,GAAG,CAAC,mBAAmB,CAAC,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC3D,IAAI,YAAY,CAAC,GAAG,CAAC,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IACrD,IAAI,uBAAuB,CAAC,GAAG,CAAC,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IAChE,OAAO,MAAM,CAAC;AACf,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,eAAe,CAAC,GAAG,GAAsB,OAAO,CAAC,GAAG;IACnE,OAAO,cAAc,CAAC,GAAG,CAAC,KAAK,QAAQ,CAAC;AACzC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAwB,IAAI,GAAG,CAAC;IAClE,MAAM;IACN,cAAc;IACd,cAAc;IACd,OAAO;IACP,UAAU;IACV,kBAAkB;IAClB,cAAc;IACd,UAAU;IACV,oBAAoB;IACpB,eAAe;IACf,oBAAoB;IACpB,eAAe;IACf,QAAQ;CACR,CAAC,CAAC","sourcesContent":["/**\n * Session-role identity: distinguishes a MAIN session (an interactive/direct `pi` session) from a\n * WORKER session (lane-bound or explicitly dispatched) — the seam every worker-scoped UAC ceiling\n * and zero-footprint store gates on (see runtime-builder.ts's `isAllowedTool`, the worktree_sync\n * tool's worker scoping, and the read-only store options threaded through the persistence layer).\n *\n * A session is a worker iff EITHER:\n * - `PI_SESSION_ROLE=worker` is set (an explicit launcher declaration),\n * - a valid `PI_PARENT_PID` declares this process as a managed child, or\n * - it is bound to a worktree-sync lane (`PI_WORKTREE_LANE`; see worktree-sync/runtime.ts) — a\n *   lane-bound session is a worker by construction, regardless of how it was launched.\n *\n * `PI_SESSION_ROLE=main` is deliberately NOT an escalation: it can never override a bound lane.\n * There is no environment value a lane-bound process can set to shed the worker ceiling — the env\n * var is additive evidence for \"worker\", never a downgrade signal.\n */\n\nimport { getParentPid } from \"./process-identity.ts\";\nimport { getBoundWorktreeLaneKey } from \"./worktree-sync/runtime.ts\";\n\nexport type SessionRole = \"main\" | \"worker\";\nexport type TerminalSessionMode = \"user\" | \"worker\";\n\nexport const PI_SESSION_ROLE_ENV = \"PI_SESSION_ROLE\";\n\nexport function isTerminalSessionMode(value: string): value is TerminalSessionMode {\n\treturn value === \"user\" || value === \"worker\";\n}\n\n/** Apply the terminal audience declaration without bypassing worker inference or UAC ceilings. */\nexport function setTerminalSessionMode(mode: TerminalSessionMode, env: NodeJS.ProcessEnv = process.env): void {\n\tif (mode === \"worker\") {\n\t\tenv[PI_SESSION_ROLE_ENV] = \"worker\";\n\t} else if (env[PI_SESSION_ROLE_ENV] !== \"worker\") {\n\t\tenv[PI_SESSION_ROLE_ENV] = \"main\";\n\t}\n}\n\n/** Derive this process's session role from the environment (env-injectable for tests). */\nexport function getSessionRole(env: NodeJS.ProcessEnv = process.env): SessionRole {\n\tif (env[PI_SESSION_ROLE_ENV] === \"worker\") return \"worker\";\n\tif (getParentPid(env) !== undefined) return \"worker\";\n\tif (getBoundWorktreeLaneKey(env) !== undefined) return \"worker\";\n\treturn \"main\";\n}\n\n/** True iff this process is a worker session (lane-bound or explicitly declared). */\nexport function isWorkerSession(env: NodeJS.ProcessEnv = process.env): boolean {\n\treturn getSessionRole(env) === \"worker\";\n}\n\n/**\n * Tools a worker session may never activate: the orchestration/self-adaptation surface that would\n * let a worker spawn its own sub-orchestration, bypass its parent to request owner input, mutate\n * settings-driven learning/model state, or shell out to the unbounded `python` execution contract.\n * `python` is load-bearing for the zero-footprint guarantee (it can write anywhere the interpreter\n * can reach); `context_scout` is\n * sub-orchestration (spawns its own isolated agent loop). `bash` is deliberately NOT included: it\n * stays available as the documented cooperative boundary (see docs/worktree-sync.md) — the same\n * trust model the lane gate already applies to foreign CLIs it cannot structurally contain.\n */\nexport const WORKER_FORBIDDEN_TOOLS: ReadonlySet<string> = new Set([\n\t\"goal\",\n\t\"ask_question\",\n\t\"secret_store\",\n\t\"skill\",\n\t\"delegate\",\n\t\"improvement_loop\",\n\t\"extensionify\",\n\t\"skillify\",\n\t\"run_toolkit_script\",\n\t\"model_fitness\",\n\t\"tmux_agent_manager\",\n\t\"context_scout\",\n\t\"python\",\n]);\n"]}

package/dist/core/skill-vault.d.ts

@@ -0,0 +1,98 @@
+import type { AgentMessage } from "@caupulican/pi-agent-core";
+import { type Skill } from "./skills.ts";
+export declare const ACTIVE_SKILL_CONTEXT_CUSTOM_TYPE = "active_skill_context";
+export declare const DEFAULT_SKILL_IDLE_TIMEOUT_MS: number;
+export declare const MAX_ACTIVE_SKILL_BODY_BYTES: number;
+export declare const MIN_ACTIVE_SKILL_BODY_BYTES: number;
+type SkillVaultRequester = "model" | "user";
+type SkillVaultUnloadReason = "explicit" | "idle_expired" | "resource_unavailable" | "budget_exceeded";
+interface LoadedSkill {
+    skill: Skill;
+    bodyBytes: number;
+    contextMessage: AgentMessage;
+    requester: SkillVaultRequester;
+    loadedAtMs: number;
+    fileDevice: number;
+    fileInode: number;
+    fileSize: number;
+    fileModifiedAtMs: number;
+    fileChangedAtMs: number;
+}
+type SkillVaultState = {
+    state: "unloaded";
+    reason?: SkillVaultUnloadReason;
+} | ({
+    state: "loaded_pending";
+} & LoadedSkill) | ({
+    state: "active";
+    lastUsedAtMs: number;
+    useCount: number;
+} & LoadedSkill);
+export interface SkillVaultStatus {
+    state: SkillVaultState["state"];
+    idleTimeoutMs: number;
+    name?: string;
+    loadedAtMs?: number;
+    lastUsedAtMs?: number;
+    idleForMs?: number;
+    expiresInMs?: number;
+    useCount?: number;
+    reason?: SkillVaultUnloadReason;
+}
+export interface SkillSearchResult {
+    candidates: Array<{
+        name: string;
+        description: string;
+    }>;
+}
+export type SkillLoadResult = {
+    ok: true;
+    state: "loaded_pending";
+    name: string;
+    replaced?: string;
+} | {
+    ok: false;
+    reason: "not_found" | "body_too_large" | "invalid_body" | "read_failed";
+    message: string;
+};
+export interface SkillVaultControllerOptions {
+    getSkills(): readonly Skill[];
+    now?: () => number;
+    idleTimeoutMs?: number;
+    getMaxBodyBytes?: () => number;
+    onSkillUsed?: (skill: Skill, usedAtMs: number) => void;
+}
+/** Reserve at most roughly one context token's worth of bytes per advertised context token. */
+export declare function resolveActiveSkillBodyByteLimit(contextWindow: number | undefined): number;
+/** One host-owned, event-driven lifecycle for lazy skill discovery and transient context projection. */
+export declare class SkillVaultController {
+    private readonly getSkills;
+    private readonly now;
+    private readonly idleTimeoutMs;
+    private readonly getMaxBodyBytes;
+    private readonly onSkillUsed;
+    private current;
+    private contextRevision;
+    constructor(options: SkillVaultControllerOptions);
+    search(rawQuery: string): SkillSearchResult;
+    load(name: string, requester: SkillVaultRequester): SkillLoadResult;
+    unload(): {
+        ok: true;
+        unloaded?: string;
+    };
+    status(): SkillVaultStatus;
+    projectContext(messages: AgentMessage[]): AgentMessage[];
+    /** Model the next request's transient skill cost without treating a diagnostic read as use. */
+    previewContext(messages: AgentMessage[]): AgentMessage[];
+    /** Monotonic identity for provider-visible skill projection changes. */
+    getContextRevision(): number;
+    private appendContext;
+    /** Record host-observed work derived from an active skill, independent of agent cooperation. */
+    noteActivity(): void;
+    private reconcile;
+    private reconcileResource;
+    private replaceState;
+    private resolveMaxBodyBytes;
+}
+export {};
+//# sourceMappingURL=skill-vault.d.ts.map

package/dist/core/skill-vault.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-vault.d.ts","sourceRoot":"","sources":["../../src/core/skill-vault.ts"],"names":[],"mappings":"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"}

package/dist/core/skill-vault.js

@@ -0,0 +1,270 @@
+import { statSync } from "node:fs";
+import { performance } from "node:perf_hooks";
+import { createCustomMessage } from "@caupulican/pi-agent-core/messages";
+import { parseFrontmatter } from "../utils/frontmatter.js";
+import { stripResourceProfileBlocks } from "./resource-profile-blocks.js";
+import { MAX_SKILL_FRONTMATTER_BYTES } from "./skills.js";
+import { readBoundedTextFileSync, sameFileVersion } from "./util/bounded-file.js";
+export const ACTIVE_SKILL_CONTEXT_CUSTOM_TYPE = "active_skill_context";
+export const DEFAULT_SKILL_IDLE_TIMEOUT_MS = 10 * 60 * 1000;
+export const MAX_ACTIVE_SKILL_BODY_BYTES = 64 * 1024;
+export const MIN_ACTIVE_SKILL_BODY_BYTES = 4 * 1024;
+const MAX_SEARCH_RESULTS = 5;
+const MAX_SEARCH_DESCRIPTION_CHARS = 240;
+function compactDescription(description) {
+    const normalized = description.replace(/\s+/g, " ").trim();
+    if (normalized.length <= MAX_SEARCH_DESCRIPTION_CHARS)
+        return normalized;
+    return `${normalized.slice(0, MAX_SEARCH_DESCRIPTION_CHARS - 1)}…`;
+}
+function queryTokens(value) {
+    return [...new Set(value.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [])];
+}
+function searchScore(skill, query, tokens) {
+    const name = skill.name.toLowerCase();
+    const description = skill.description.toLowerCase();
+    let score = name === query ? 100 : name.includes(query) ? 40 : description.includes(query) ? 20 : 0;
+    for (const token of tokens) {
+        if (name === token)
+            score += 16;
+        else if (name.includes(token))
+            score += 8;
+        if (description.includes(token))
+            score += 3;
+    }
+    return score;
+}
+function activeSkillContext(skill, body) {
+    return [`ACTIVE SKILL ${skill.name}`, `BASE ${skill.baseDir}`, "NON-NEGOTIABLE WHILE ACTIVE:", body].join("\n");
+}
+/** Reserve at most roughly one context token's worth of bytes per advertised context token. */
+export function resolveActiveSkillBodyByteLimit(contextWindow) {
+    if (contextWindow === undefined || !Number.isFinite(contextWindow) || contextWindow <= 0) {
+        return MAX_ACTIVE_SKILL_BODY_BYTES;
+    }
+    return Math.min(MAX_ACTIVE_SKILL_BODY_BYTES, Math.max(MIN_ACTIVE_SKILL_BODY_BYTES, Math.floor(contextWindow)));
+}
+/** One host-owned, event-driven lifecycle for lazy skill discovery and transient context projection. */
+export class SkillVaultController {
+    constructor(options) {
+        this.current = { state: "unloaded" };
+        this.contextRevision = 0;
+        if (!Number.isFinite(options.idleTimeoutMs ?? DEFAULT_SKILL_IDLE_TIMEOUT_MS)) {
+            throw new TypeError("Skill idle timeout must be finite.");
+        }
+        this.getSkills = options.getSkills;
+        this.now = options.now ?? (() => performance.now());
+        this.idleTimeoutMs = Math.max(1, options.idleTimeoutMs ?? DEFAULT_SKILL_IDLE_TIMEOUT_MS);
+        this.getMaxBodyBytes = options.getMaxBodyBytes ?? (() => MAX_ACTIVE_SKILL_BODY_BYTES);
+        this.onSkillUsed = options.onSkillUsed;
+    }
+    search(rawQuery) {
+        const query = rawQuery.trim().toLowerCase();
+        const tokens = queryTokens(query);
+        if (!query || tokens.length === 0)
+            return { candidates: [] };
+        const candidates = this.getSkills()
+            .filter((skill) => !skill.disableModelInvocation)
+            .map((skill) => ({ skill, score: searchScore(skill, query, tokens) }))
+            .filter((entry) => entry.score > 0)
+            .sort((left, right) => right.score - left.score || left.skill.name.localeCompare(right.skill.name))
+            .slice(0, MAX_SEARCH_RESULTS)
+            .map(({ skill }) => ({ name: skill.name, description: compactDescription(skill.description) }));
+        return { candidates };
+    }
+    load(name, requester) {
+        const skill = this.getSkills().find((candidate) => candidate.name === name && (requester === "user" || !candidate.disableModelInvocation));
+        if (!skill) {
+            return { ok: false, reason: "not_found", message: `No eligible skill named ${JSON.stringify(name)}.` };
+        }
+        const maxBodyBytes = this.resolveMaxBodyBytes();
+        let before;
+        try {
+            before = statSync(skill.filePath);
+        }
+        catch (error) {
+            return { ok: false, reason: "read_failed", message: error instanceof Error ? error.message : String(error) };
+        }
+        let raw;
+        try {
+            raw = readBoundedTextFileSync(skill.filePath, maxBodyBytes + MAX_SKILL_FRONTMATTER_BYTES, `Skill ${JSON.stringify(skill.name)}`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return message.includes("exceeds its byte limit")
+                ? {
+                    ok: false,
+                    reason: "body_too_large",
+                    message: `Skill body exceeds ${maxBodyBytes} bytes; not truncated.`,
+                }
+                : { ok: false, reason: "read_failed", message };
+        }
+        const parsed = parseFrontmatter(raw);
+        const currentName = parsed.frontmatter.name ?? skill.name;
+        const body = stripResourceProfileBlocks(parsed.body).trim();
+        if (currentName !== skill.name || !parsed.frontmatter.description || !body) {
+            return { ok: false, reason: "invalid_body", message: "Skill metadata changed or its body is empty." };
+        }
+        const bodyBytes = Buffer.byteLength(body, "utf8");
+        if (bodyBytes > maxBodyBytes) {
+            return {
+                ok: false,
+                reason: "body_too_large",
+                message: `Skill body exceeds ${maxBodyBytes} bytes; not truncated.`,
+            };
+        }
+        let file;
+        try {
+            file = statSync(skill.filePath);
+        }
+        catch (error) {
+            return { ok: false, reason: "read_failed", message: error instanceof Error ? error.message : String(error) };
+        }
+        if (!sameFileVersion(before, file)) {
+            return { ok: false, reason: "read_failed", message: "Skill changed while it was being loaded." };
+        }
+        const replaced = this.current.state === "unloaded" ? undefined : this.current.skill.name;
+        this.replaceState({
+            state: "loaded_pending",
+            skill,
+            bodyBytes,
+            contextMessage: createCustomMessage(ACTIVE_SKILL_CONTEXT_CUSTOM_TYPE, activeSkillContext(skill, body), false, { name: skill.name, requestLocal: true }, new Date().toISOString()),
+            requester,
+            loadedAtMs: this.now(),
+            fileDevice: file.dev,
+            fileInode: file.ino,
+            fileSize: file.size,
+            fileModifiedAtMs: file.mtimeMs,
+            fileChangedAtMs: file.ctimeMs,
+        });
+        return { ok: true, state: "loaded_pending", name: skill.name, ...(replaced ? { replaced } : {}) };
+    }
+    unload() {
+        const unloaded = this.current.state === "unloaded" ? undefined : this.current.skill.name;
+        this.replaceState({ state: "unloaded", reason: "explicit" });
+        return { ok: true, ...(unloaded ? { unloaded } : {}) };
+    }
+    status() {
+        const now = this.now();
+        this.reconcile(now);
+        if (this.current.state === "unloaded") {
+            return {
+                state: "unloaded",
+                idleTimeoutMs: this.idleTimeoutMs,
+                ...(this.current.reason ? { reason: this.current.reason } : {}),
+            };
+        }
+        if (this.current.state === "loaded_pending") {
+            return {
+                state: "loaded_pending",
+                idleTimeoutMs: this.idleTimeoutMs,
+                name: this.current.skill.name,
+                loadedAtMs: this.current.loadedAtMs,
+            };
+        }
+        const idleForMs = Math.max(0, now - this.current.lastUsedAtMs);
+        return {
+            state: "active",
+            idleTimeoutMs: this.idleTimeoutMs,
+            name: this.current.skill.name,
+            loadedAtMs: this.current.loadedAtMs,
+            lastUsedAtMs: this.current.lastUsedAtMs,
+            idleForMs,
+            expiresInMs: Math.max(0, this.idleTimeoutMs - idleForMs),
+            useCount: this.current.useCount,
+        };
+    }
+    projectContext(messages) {
+        const now = this.now();
+        this.reconcile(now);
+        if (this.current.state === "unloaded")
+            return messages;
+        const loaded = this.current;
+        const firstUse = loaded.state === "loaded_pending";
+        const useCount = firstUse ? 1 : loaded.useCount + 1;
+        this.current = { ...loaded, state: "active", lastUsedAtMs: now, useCount };
+        if (firstUse) {
+            try {
+                this.onSkillUsed?.(loaded.skill, now);
+            }
+            catch {
+                // Usage telemetry must never block skill application.
+            }
+        }
+        return this.appendContext(messages, loaded);
+    }
+    /** Model the next request's transient skill cost without treating a diagnostic read as use. */
+    previewContext(messages) {
+        this.reconcile(this.now());
+        return this.current.state === "unloaded" ? messages : this.appendContext(messages, this.current);
+    }
+    /** Monotonic identity for provider-visible skill projection changes. */
+    getContextRevision() {
+        this.reconcile(this.now());
+        return this.contextRevision;
+    }
+    appendContext(messages, loaded) {
+        return [...messages, loaded.contextMessage];
+    }
+    /** Record host-observed work derived from an active skill, independent of agent cooperation. */
+    noteActivity() {
+        const now = this.now();
+        if (this.current.state === "active") {
+            this.current = { ...this.current, lastUsedAtMs: now };
+        }
+    }
+    reconcile(now) {
+        if (!this.reconcileResource())
+            return;
+        const current = this.current;
+        if (current.state === "unloaded")
+            return;
+        const lastUsedAtMs = current.state === "loaded_pending" ? current.loadedAtMs : current.lastUsedAtMs;
+        if (now - lastUsedAtMs >= this.idleTimeoutMs) {
+            this.replaceState({ state: "unloaded", reason: "idle_expired" });
+        }
+    }
+    reconcileResource() {
+        if (this.current.state === "unloaded")
+            return false;
+        const loaded = this.current;
+        if (loaded.bodyBytes > this.resolveMaxBodyBytes()) {
+            this.replaceState({ state: "unloaded", reason: "budget_exceeded" });
+            return false;
+        }
+        const currentSkill = this.getSkills().find((skill) => skill.name === loaded.skill.name &&
+            skill.filePath === loaded.skill.filePath &&
+            (loaded.requester === "user" || !skill.disableModelInvocation));
+        if (!currentSkill) {
+            this.replaceState({ state: "unloaded", reason: "resource_unavailable" });
+            return false;
+        }
+        try {
+            const file = statSync(loaded.skill.filePath);
+            if (file.dev !== loaded.fileDevice ||
+                file.ino !== loaded.fileInode ||
+                file.size !== loaded.fileSize ||
+                file.mtimeMs !== loaded.fileModifiedAtMs ||
+                file.ctimeMs !== loaded.fileChangedAtMs) {
+                this.replaceState({ state: "unloaded", reason: "resource_unavailable" });
+                return false;
+            }
+        }
+        catch {
+            this.replaceState({ state: "unloaded", reason: "resource_unavailable" });
+            return false;
+        }
+        return true;
+    }
+    replaceState(state) {
+        this.current = state;
+        this.contextRevision++;
+    }
+    resolveMaxBodyBytes() {
+        const configured = this.getMaxBodyBytes();
+        if (!Number.isFinite(configured))
+            return 1;
+        return Math.min(MAX_ACTIVE_SKILL_BODY_BYTES, Math.max(1, Math.floor(configured)));
+    }
+}
+//# sourceMappingURL=skill-vault.js.map

package/dist/core/skill-vault.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-vault.js","sourceRoot":"","sources":["../../src/core/skill-vault.ts"],"names":[],"mappings":"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","sourcesContent":["import { statSync } from \"node:fs\";\nimport { performance } from \"node:perf_hooks\";\nimport type { AgentMessage } from \"@caupulican/pi-agent-core\";\nimport { createCustomMessage } from \"@caupulican/pi-agent-core/messages\";\nimport { parseFrontmatter } from \"../utils/frontmatter.ts\";\nimport { stripResourceProfileBlocks } from \"./resource-profile-blocks.ts\";\nimport { MAX_SKILL_FRONTMATTER_BYTES, type Skill, type SkillFrontmatter } from \"./skills.ts\";\nimport { readBoundedTextFileSync, sameFileVersion } from \"./util/bounded-file.ts\";\n\nexport const ACTIVE_SKILL_CONTEXT_CUSTOM_TYPE = \"active_skill_context\";\nexport const DEFAULT_SKILL_IDLE_TIMEOUT_MS = 10 * 60 * 1000;\nexport const MAX_ACTIVE_SKILL_BODY_BYTES = 64 * 1024;\nexport const MIN_ACTIVE_SKILL_BODY_BYTES = 4 * 1024;\nconst MAX_SEARCH_RESULTS = 5;\nconst MAX_SEARCH_DESCRIPTION_CHARS = 240;\n\ntype SkillVaultRequester = \"model\" | \"user\";\ntype SkillVaultUnloadReason = \"explicit\" | \"idle_expired\" | \"resource_unavailable\" | \"budget_exceeded\";\n\ninterface LoadedSkill {\n\tskill: Skill;\n\tbodyBytes: number;\n\tcontextMessage: AgentMessage;\n\trequester: SkillVaultRequester;\n\tloadedAtMs: number;\n\tfileDevice: number;\n\tfileInode: number;\n\tfileSize: number;\n\tfileModifiedAtMs: number;\n\tfileChangedAtMs: number;\n}\n\ntype SkillVaultState =\n\t| { state: \"unloaded\"; reason?: SkillVaultUnloadReason }\n\t| ({ state: \"loaded_pending\" } & LoadedSkill)\n\t| ({ state: \"active\"; lastUsedAtMs: number; useCount: number } & LoadedSkill);\n\nexport interface SkillVaultStatus {\n\tstate: SkillVaultState[\"state\"];\n\tidleTimeoutMs: number;\n\tname?: string;\n\tloadedAtMs?: number;\n\tlastUsedAtMs?: number;\n\tidleForMs?: number;\n\texpiresInMs?: number;\n\tuseCount?: number;\n\treason?: SkillVaultUnloadReason;\n}\n\nexport interface SkillSearchResult {\n\tcandidates: Array<{ name: string; description: string }>;\n}\n\nexport type SkillLoadResult =\n\t| { ok: true; state: \"loaded_pending\"; name: string; replaced?: string }\n\t| { ok: false; reason: \"not_found\" | \"body_too_large\" | \"invalid_body\" | \"read_failed\"; message: string };\n\nexport interface SkillVaultControllerOptions {\n\tgetSkills(): readonly Skill[];\n\tnow?: () => number;\n\tidleTimeoutMs?: number;\n\tgetMaxBodyBytes?: () => number;\n\tonSkillUsed?: (skill: Skill, usedAtMs: number) => void;\n}\n\nfunction compactDescription(description: string): string {\n\tconst normalized = description.replace(/\\s+/g, \" \").trim();\n\tif (normalized.length <= MAX_SEARCH_DESCRIPTION_CHARS) return normalized;\n\treturn `${normalized.slice(0, MAX_SEARCH_DESCRIPTION_CHARS - 1)}…`;\n}\n\nfunction queryTokens(value: string): string[] {\n\treturn [...new Set(value.toLowerCase().match(/[\\p{L}\\p{N}]+/gu) ?? [])];\n}\n\nfunction searchScore(skill: Skill, query: string, tokens: readonly string[]): number {\n\tconst name = skill.name.toLowerCase();\n\tconst description = skill.description.toLowerCase();\n\tlet score = name === query ? 100 : name.includes(query) ? 40 : description.includes(query) ? 20 : 0;\n\tfor (const token of tokens) {\n\t\tif (name === token) score += 16;\n\t\telse if (name.includes(token)) score += 8;\n\t\tif (description.includes(token)) score += 3;\n\t}\n\treturn score;\n}\n\nfunction activeSkillContext(skill: Skill, body: string): string {\n\treturn [`ACTIVE SKILL ${skill.name}`, `BASE ${skill.baseDir}`, \"NON-NEGOTIABLE WHILE ACTIVE:\", body].join(\"\\n\");\n}\n\n/** Reserve at most roughly one context token's worth of bytes per advertised context token. */\nexport function resolveActiveSkillBodyByteLimit(contextWindow: number | undefined): number {\n\tif (contextWindow === undefined || !Number.isFinite(contextWindow) || contextWindow <= 0) {\n\t\treturn MAX_ACTIVE_SKILL_BODY_BYTES;\n\t}\n\treturn Math.min(MAX_ACTIVE_SKILL_BODY_BYTES, Math.max(MIN_ACTIVE_SKILL_BODY_BYTES, Math.floor(contextWindow)));\n}\n\n/** One host-owned, event-driven lifecycle for lazy skill discovery and transient context projection. */\nexport class SkillVaultController {\n\tprivate readonly getSkills: () => readonly Skill[];\n\tprivate readonly now: () => number;\n\tprivate readonly idleTimeoutMs: number;\n\tprivate readonly getMaxBodyBytes: () => number;\n\tprivate readonly onSkillUsed: ((skill: Skill, usedAtMs: number) => void) | undefined;\n\tprivate current: SkillVaultState = { state: \"unloaded\" };\n\tprivate contextRevision = 0;\n\n\tconstructor(options: SkillVaultControllerOptions) {\n\t\tif (!Number.isFinite(options.idleTimeoutMs ?? DEFAULT_SKILL_IDLE_TIMEOUT_MS)) {\n\t\t\tthrow new TypeError(\"Skill idle timeout must be finite.\");\n\t\t}\n\t\tthis.getSkills = options.getSkills;\n\t\tthis.now = options.now ?? (() => performance.now());\n\t\tthis.idleTimeoutMs = Math.max(1, options.idleTimeoutMs ?? DEFAULT_SKILL_IDLE_TIMEOUT_MS);\n\t\tthis.getMaxBodyBytes = options.getMaxBodyBytes ?? (() => MAX_ACTIVE_SKILL_BODY_BYTES);\n\t\tthis.onSkillUsed = options.onSkillUsed;\n\t}\n\n\tsearch(rawQuery: string): SkillSearchResult {\n\t\tconst query = rawQuery.trim().toLowerCase();\n\t\tconst tokens = queryTokens(query);\n\t\tif (!query || tokens.length === 0) return { candidates: [] };\n\t\tconst candidates = this.getSkills()\n\t\t\t.filter((skill) => !skill.disableModelInvocation)\n\t\t\t.map((skill) => ({ skill, score: searchScore(skill, query, tokens) }))\n\t\t\t.filter((entry) => entry.score > 0)\n\t\t\t.sort((left, right) => right.score - left.score || left.skill.name.localeCompare(right.skill.name))\n\t\t\t.slice(0, MAX_SEARCH_RESULTS)\n\t\t\t.map(({ skill }) => ({ name: skill.name, description: compactDescription(skill.description) }));\n\t\treturn { candidates };\n\t}\n\n\tload(name: string, requester: SkillVaultRequester): SkillLoadResult {\n\t\tconst skill = this.getSkills().find(\n\t\t\t(candidate) => candidate.name === name && (requester === \"user\" || !candidate.disableModelInvocation),\n\t\t);\n\t\tif (!skill) {\n\t\t\treturn { ok: false, reason: \"not_found\", message: `No eligible skill named ${JSON.stringify(name)}.` };\n\t\t}\n\t\tconst maxBodyBytes = this.resolveMaxBodyBytes();\n\t\tlet before: ReturnType<typeof statSync>;\n\t\ttry {\n\t\t\tbefore = statSync(skill.filePath);\n\t\t} catch (error) {\n\t\t\treturn { ok: false, reason: \"read_failed\", message: error instanceof Error ? error.message : String(error) };\n\t\t}\n\t\tlet raw: string;\n\t\ttry {\n\t\t\traw = readBoundedTextFileSync(\n\t\t\t\tskill.filePath,\n\t\t\t\tmaxBodyBytes + MAX_SKILL_FRONTMATTER_BYTES,\n\t\t\t\t`Skill ${JSON.stringify(skill.name)}`,\n\t\t\t);\n\t\t} catch (error) {\n\t\t\tconst message = error instanceof Error ? error.message : String(error);\n\t\t\treturn message.includes(\"exceeds its byte limit\")\n\t\t\t\t? {\n\t\t\t\t\t\tok: false,\n\t\t\t\t\t\treason: \"body_too_large\",\n\t\t\t\t\t\tmessage: `Skill body exceeds ${maxBodyBytes} bytes; not truncated.`,\n\t\t\t\t\t}\n\t\t\t\t: { ok: false, reason: \"read_failed\", message };\n\t\t}\n\t\tconst parsed = parseFrontmatter<SkillFrontmatter>(raw);\n\t\tconst currentName = parsed.frontmatter.name ?? skill.name;\n\t\tconst body = stripResourceProfileBlocks(parsed.body).trim();\n\t\tif (currentName !== skill.name || !parsed.frontmatter.description || !body) {\n\t\t\treturn { ok: false, reason: \"invalid_body\", message: \"Skill metadata changed or its body is empty.\" };\n\t\t}\n\t\tconst bodyBytes = Buffer.byteLength(body, \"utf8\");\n\t\tif (bodyBytes > maxBodyBytes) {\n\t\t\treturn {\n\t\t\t\tok: false,\n\t\t\t\treason: \"body_too_large\",\n\t\t\t\tmessage: `Skill body exceeds ${maxBodyBytes} bytes; not truncated.`,\n\t\t\t};\n\t\t}\n\t\tlet file: ReturnType<typeof statSync>;\n\t\ttry {\n\t\t\tfile = statSync(skill.filePath);\n\t\t} catch (error) {\n\t\t\treturn { ok: false, reason: \"read_failed\", message: error instanceof Error ? error.message : String(error) };\n\t\t}\n\t\tif (!sameFileVersion(before, file)) {\n\t\t\treturn { ok: false, reason: \"read_failed\", message: \"Skill changed while it was being loaded.\" };\n\t\t}\n\t\tconst replaced = this.current.state === \"unloaded\" ? undefined : this.current.skill.name;\n\t\tthis.replaceState({\n\t\t\tstate: \"loaded_pending\",\n\t\t\tskill,\n\t\t\tbodyBytes,\n\t\t\tcontextMessage: createCustomMessage(\n\t\t\t\tACTIVE_SKILL_CONTEXT_CUSTOM_TYPE,\n\t\t\t\tactiveSkillContext(skill, body),\n\t\t\t\tfalse,\n\t\t\t\t{ name: skill.name, requestLocal: true },\n\t\t\t\tnew Date().toISOString(),\n\t\t\t),\n\t\t\trequester,\n\t\t\tloadedAtMs: this.now(),\n\t\t\tfileDevice: file.dev,\n\t\t\tfileInode: file.ino,\n\t\t\tfileSize: file.size,\n\t\t\tfileModifiedAtMs: file.mtimeMs,\n\t\t\tfileChangedAtMs: file.ctimeMs,\n\t\t});\n\t\treturn { ok: true, state: \"loaded_pending\", name: skill.name, ...(replaced ? { replaced } : {}) };\n\t}\n\n\tunload(): { ok: true; unloaded?: string } {\n\t\tconst unloaded = this.current.state === \"unloaded\" ? undefined : this.current.skill.name;\n\t\tthis.replaceState({ state: \"unloaded\", reason: \"explicit\" });\n\t\treturn { ok: true, ...(unloaded ? { unloaded } : {}) };\n\t}\n\n\tstatus(): SkillVaultStatus {\n\t\tconst now = this.now();\n\t\tthis.reconcile(now);\n\t\tif (this.current.state === \"unloaded\") {\n\t\t\treturn {\n\t\t\t\tstate: \"unloaded\",\n\t\t\t\tidleTimeoutMs: this.idleTimeoutMs,\n\t\t\t\t...(this.current.reason ? { reason: this.current.reason } : {}),\n\t\t\t};\n\t\t}\n\t\tif (this.current.state === \"loaded_pending\") {\n\t\t\treturn {\n\t\t\t\tstate: \"loaded_pending\",\n\t\t\t\tidleTimeoutMs: this.idleTimeoutMs,\n\t\t\t\tname: this.current.skill.name,\n\t\t\t\tloadedAtMs: this.current.loadedAtMs,\n\t\t\t};\n\t\t}\n\t\tconst idleForMs = Math.max(0, now - this.current.lastUsedAtMs);\n\t\treturn {\n\t\t\tstate: \"active\",\n\t\t\tidleTimeoutMs: this.idleTimeoutMs,\n\t\t\tname: this.current.skill.name,\n\t\t\tloadedAtMs: this.current.loadedAtMs,\n\t\t\tlastUsedAtMs: this.current.lastUsedAtMs,\n\t\t\tidleForMs,\n\t\t\texpiresInMs: Math.max(0, this.idleTimeoutMs - idleForMs),\n\t\t\tuseCount: this.current.useCount,\n\t\t};\n\t}\n\n\tprojectContext(messages: AgentMessage[]): AgentMessage[] {\n\t\tconst now = this.now();\n\t\tthis.reconcile(now);\n\t\tif (this.current.state === \"unloaded\") return messages;\n\t\tconst loaded = this.current;\n\t\tconst firstUse = loaded.state === \"loaded_pending\";\n\t\tconst useCount = firstUse ? 1 : loaded.useCount + 1;\n\t\tthis.current = { ...loaded, state: \"active\", lastUsedAtMs: now, useCount };\n\t\tif (firstUse) {\n\t\t\ttry {\n\t\t\t\tthis.onSkillUsed?.(loaded.skill, now);\n\t\t\t} catch {\n\t\t\t\t// Usage telemetry must never block skill application.\n\t\t\t}\n\t\t}\n\t\treturn this.appendContext(messages, loaded);\n\t}\n\n\t/** Model the next request's transient skill cost without treating a diagnostic read as use. */\n\tpreviewContext(messages: AgentMessage[]): AgentMessage[] {\n\t\tthis.reconcile(this.now());\n\t\treturn this.current.state === \"unloaded\" ? messages : this.appendContext(messages, this.current);\n\t}\n\n\t/** Monotonic identity for provider-visible skill projection changes. */\n\tgetContextRevision(): number {\n\t\tthis.reconcile(this.now());\n\t\treturn this.contextRevision;\n\t}\n\n\tprivate appendContext(messages: AgentMessage[], loaded: LoadedSkill): AgentMessage[] {\n\t\treturn [...messages, loaded.contextMessage];\n\t}\n\n\t/** Record host-observed work derived from an active skill, independent of agent cooperation. */\n\tnoteActivity(): void {\n\t\tconst now = this.now();\n\t\tif (this.current.state === \"active\") {\n\t\t\tthis.current = { ...this.current, lastUsedAtMs: now };\n\t\t}\n\t}\n\n\tprivate reconcile(now: number): void {\n\t\tif (!this.reconcileResource()) return;\n\t\tconst current = this.current;\n\t\tif (current.state === \"unloaded\") return;\n\t\tconst lastUsedAtMs = current.state === \"loaded_pending\" ? current.loadedAtMs : current.lastUsedAtMs;\n\t\tif (now - lastUsedAtMs >= this.idleTimeoutMs) {\n\t\t\tthis.replaceState({ state: \"unloaded\", reason: \"idle_expired\" });\n\t\t}\n\t}\n\n\tprivate reconcileResource(): boolean {\n\t\tif (this.current.state === \"unloaded\") return false;\n\t\tconst loaded = this.current;\n\t\tif (loaded.bodyBytes > this.resolveMaxBodyBytes()) {\n\t\t\tthis.replaceState({ state: \"unloaded\", reason: \"budget_exceeded\" });\n\t\t\treturn false;\n\t\t}\n\t\tconst currentSkill = this.getSkills().find(\n\t\t\t(skill) =>\n\t\t\t\tskill.name === loaded.skill.name &&\n\t\t\t\tskill.filePath === loaded.skill.filePath &&\n\t\t\t\t(loaded.requester === \"user\" || !skill.disableModelInvocation),\n\t\t);\n\t\tif (!currentSkill) {\n\t\t\tthis.replaceState({ state: \"unloaded\", reason: \"resource_unavailable\" });\n\t\t\treturn false;\n\t\t}\n\t\ttry {\n\t\t\tconst file = statSync(loaded.skill.filePath);\n\t\t\tif (\n\t\t\t\tfile.dev !== loaded.fileDevice ||\n\t\t\t\tfile.ino !== loaded.fileInode ||\n\t\t\t\tfile.size !== loaded.fileSize ||\n\t\t\t\tfile.mtimeMs !== loaded.fileModifiedAtMs ||\n\t\t\t\tfile.ctimeMs !== loaded.fileChangedAtMs\n\t\t\t) {\n\t\t\t\tthis.replaceState({ state: \"unloaded\", reason: \"resource_unavailable\" });\n\t\t\t\treturn false;\n\t\t\t}\n\t\t} catch {\n\t\t\tthis.replaceState({ state: \"unloaded\", reason: \"resource_unavailable\" });\n\t\t\treturn false;\n\t\t}\n\t\treturn true;\n\t}\n\n\tprivate replaceState(state: SkillVaultState): void {\n\t\tthis.current = state;\n\t\tthis.contextRevision++;\n\t}\n\n\tprivate resolveMaxBodyBytes(): number {\n\t\tconst configured = this.getMaxBodyBytes();\n\t\tif (!Number.isFinite(configured)) return 1;\n\t\treturn Math.min(MAX_ACTIVE_SKILL_BODY_BYTES, Math.max(1, Math.floor(configured)));\n\t}\n}\n"]}

package/dist/core/skills.d.ts

@@ -1,12 +1,16 @@
 import type { ThinkingLevel } from "@caupulican/pi-agent-core";
 import type { ResourceDiagnostic } from "./diagnostics.ts";
 import { type SourceInfo } from "./source-info.ts";
+/** Discovery retains only this bounded metadata prefix, never the whole skill body. */
+export declare const MAX_SKILL_FRONTMATTER_BYTES: number;
 export interface SkillFrontmatter {
     name?: string;
     description?: string;
     "disable-model-invocation"?: boolean;
     /** Optional thinking-level hint (R1 follow-up); see Skill.thinking. */
     thinking?: string;
+    /** Reflection-generated skill marker used by the curator. */
+    promoted?: boolean;
     [key: string]: unknown;
 }
 export interface Skill {
@@ -16,6 +20,7 @@ export interface Skill {
     baseDir: string;
     sourceInfo: SourceInfo;
     disableModelInvocation: boolean;
+    promoted?: boolean;
     /**
      * Optional thinking-level hint parsed from frontmatter (R1 follow-up: skill-surfaced thinking
      * governance, alongside resource-profile thinking). Core only parses and surfaces this value —
@@ -45,6 +50,11 @@ export interface LoadSkillsFromDirOptions {
     /** Profile UAC gate: when provided, files it denies are never read from disk. */
     isPathAllowed?: (path: string) => boolean;
 }
+/**
+ * Read one stable, bounded frontmatter prefix. The closing delimiter ends the read, so discovery
+ * cost depends on metadata size, never body size. Unterminated metadata fails at the explicit cap.
+ */
+export declare function readSkillFrontmatterFile(filePath: string): string;
 /**
  * Load skills from a directory.
  *
@@ -54,15 +64,6 @@ export interface LoadSkillsFromDirOptions {
  * - recurse into subdirectories to find SKILL.md
  */
 export declare function loadSkillsFromDir(options: LoadSkillsFromDirOptions): LoadSkillsResult;
-/**
- * Format skills for inclusion in a system prompt.
- * Uses XML format per Agent Skills standard.
- * See: https://agentskills.io/integrate-skills
- *
- * Skills with disableModelInvocation=true are excluded from the prompt
- * (they can only be invoked explicitly via /skill:name commands).
- */
-export declare function formatSkillsForPrompt(skills: Skill[]): string;
 export interface LoadSkillsOptions {
     /** Working directory for project-local skills. */
     cwd: string;

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

@@ -1 +1 @@
-{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/core/skills.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAM/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAI3D,OAAO,EAA6B,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAkB9E,MAAM,WAAW,gBAAgB;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,KAAK;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,UAAU,CAAC;IACvB,sBAAsB,EAAE,OAAO,CAAC;IAChC;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAChC,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,WAAW,EAAE,kBAAkB,EAAE,CAAC;CAClC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAoBxD;AAiBD,MAAM,WAAW,wBAAwB;IACxC,mCAAmC;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CAC1C;AA0BD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,gBAAgB,CAGrF;AAkFD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CA6B7D;AAED,MAAM,WAAW,iBAAiB;IACjC,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,0CAA0C;IAC1C,eAAe,EAAE,OAAO,CAAC;IACzB,iFAAiF;IACjF,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CAC1C;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,gBAAgB,CAiGvE"}
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/core/skills.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAM/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAG3D,OAAO,EAA6B,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9E,uFAAuF;AACvF,eAAO,MAAM,2BAA2B,QAAY,CAAC;AAgBrD,MAAM,WAAW,gBAAgB;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,KAAK;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,UAAU,CAAC;IACvB,sBAAsB,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAChC,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,WAAW,EAAE,kBAAkB,EAAE,CAAC;CAClC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAoBxD;AAiBD,MAAM,WAAW,wBAAwB;IACxC,mCAAmC;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CAC1C;AA0BD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA6BjE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,gBAAgB,CAGrF;AAuED,MAAM,WAAW,iBAAiB;IACjC,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,0CAA0C;IAC1C,eAAe,EAAE,OAAO,CAAC;IACzB,iFAAiF;IACjF,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CAC1C;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,gBAAgB,CAiGvE"}

package/dist/core/skills.js

@@ -1,14 +1,15 @@
-import { existsSync, readFileSync, statSync } from "fs";
+import { closeSync, existsSync, fstatSync, openSync, readSync, statSync } from "fs";
 import { basename, dirname, join, resolve } from "path";
 import { CONFIG_DIR_NAME, getAgentDir } from "../config.js";
 import { parseFrontmatter } from "../utils/frontmatter.js";
 import { canonicalizePath, resolvePath } from "../utils/paths.js";
-import { escapePromptXml } from "./prompt-markup.js";
 import { isResourcePathWithin } from "./resource-traversal.js";
 import { discoverSkillFiles } from "./skill-discovery.js";
 import { createSyntheticSourceInfo } from "./source-info.js";
-/** Max name length per spec */
-const MAX_SKILL_FILE_BYTES = 8 * 1024 * 1024;
+import { sameFileVersion } from "./util/bounded-file.js";
+/** Discovery retains only this bounded metadata prefix, never the whole skill body. */
+export const MAX_SKILL_FRONTMATTER_BYTES = 16 * 1024;
+const SKILL_FRONTMATTER_READ_CHUNK_BYTES = 1024;
 const MAX_NAME_LENGTH = 64;
 /** Max description length per spec */
 const MAX_DESCRIPTION_LENGTH = 1024;
@@ -75,6 +76,41 @@ function createSkillSourceInfo(filePath, baseDir, source) {
             return createSyntheticSourceInfo(filePath, { source, baseDir });
     }
 }
+/**
+ * Read one stable, bounded frontmatter prefix. The closing delimiter ends the read, so discovery
+ * cost depends on metadata size, never body size. Unterminated metadata fails at the explicit cap.
+ */
+export function readSkillFrontmatterFile(filePath) {
+    const fileDescriptor = openSync(filePath, "r");
+    try {
+        const before = fstatSync(fileDescriptor);
+        if (!before.isFile())
+            throw new Error("Skill is not a regular file.");
+        const chunks = [];
+        let totalBytes = 0;
+        while (totalBytes < MAX_SKILL_FRONTMATTER_BYTES) {
+            const chunk = Buffer.allocUnsafe(Math.min(SKILL_FRONTMATTER_READ_CHUNK_BYTES, MAX_SKILL_FRONTMATTER_BYTES - totalBytes));
+            const bytesRead = readSync(fileDescriptor, chunk, 0, chunk.length, totalBytes);
+            if (bytesRead > 0) {
+                chunks.push(chunk.subarray(0, bytesRead));
+                totalBytes += bytesRead;
+            }
+            const prefix = Buffer.concat(chunks, totalBytes).toString("utf8").replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+            const hasOpeningDelimiter = prefix.length >= 3 && prefix.startsWith("---");
+            const closingDelimiter = hasOpeningDelimiter ? prefix.indexOf("\n---", 3) : -1;
+            if (!hasOpeningDelimiter || closingDelimiter !== -1 || bytesRead === 0) {
+                const after = fstatSync(fileDescriptor);
+                if (!sameFileVersion(before, after))
+                    throw new Error("Skill changed while metadata was being read.");
+                return closingDelimiter === -1 ? prefix : prefix.slice(0, closingDelimiter + 4);
+            }
+        }
+        throw new Error(`Skill frontmatter exceeds ${MAX_SKILL_FRONTMATTER_BYTES} bytes or is unterminated.`);
+    }
+    finally {
+        closeSync(fileDescriptor);
+    }
+}
 /**
  * Load skills from a directory.
  *
@@ -104,19 +140,7 @@ function loadSkillsFromDirInternal(dir, source, isPathAllowed) {
 function loadSkillFromFile(filePath, source) {
     const diagnostics = [];
     try {
-        // A skill file is prompt material; anything beyond this is a mistake (or
-        // hostile) and would otherwise be loaded whole into the heap at startup.
-        const { size } = statSync(filePath);
-        if (size > MAX_SKILL_FILE_BYTES) {
-            diagnostics.push({
-                type: "warning",
-                path: filePath,
-                message: `Skill file is ${Math.round(size / (1024 * 1024))}MB (limit ${Math.round(MAX_SKILL_FILE_BYTES / (1024 * 1024))}MB); skipped.`,
-            });
-            return { skill: null, diagnostics };
-        }
-        const rawContent = readFileSync(filePath, "utf-8");
-        const { frontmatter } = parseFrontmatter(rawContent);
+        const { frontmatter } = parseFrontmatter(readSkillFrontmatterFile(filePath));
         const skillDir = dirname(filePath);
         const parentDirName = basename(skillDir);
         // Validate description
@@ -143,6 +167,7 @@ function loadSkillFromFile(filePath, source) {
                 baseDir: skillDir,
                 sourceInfo: createSkillSourceInfo(filePath, skillDir, source),
                 disableModelInvocation: frontmatter["disable-model-invocation"] === true,
+                promoted: frontmatter.promoted === true,
                 thinking: isSkillThinkingLevel(frontmatter.thinking) ? frontmatter.thinking : undefined,
             },
             diagnostics,
@@ -154,39 +179,6 @@ function loadSkillFromFile(filePath, source) {
         return { skill: null, diagnostics };
     }
 }
-/**
- * Format skills for inclusion in a system prompt.
- * Uses XML format per Agent Skills standard.
- * See: https://agentskills.io/integrate-skills
- *
- * Skills with disableModelInvocation=true are excluded from the prompt
- * (they can only be invoked explicitly via /skill:name commands).
- */
-export function formatSkillsForPrompt(skills) {
-    const visibleSkills = skills.filter((s) => !s.disableModelInvocation);
-    if (visibleSkills.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 multiple skills seem relevant, prefer the narrowest task-specific skill; combine skills only when their descriptions clearly cover distinct parts of the request.",
-        "Do not use a skill merely because it is loaded; if the fit is unclear, inspect the skill or ask before applying broad behavior.",
-        "Resource-profile blocks inside skill files are configuration data, not task instructions, and are stripped from /skill expansion.",
-        "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 visibleSkills) {
-        lines.push("  <skill>");
-        lines.push(`    <name>${escapePromptXml(skill.name)}</name>`);
-        lines.push(`    <description>${escapePromptXml(skill.description)}</description>`);
-        lines.push(`    <location>${escapePromptXml(skill.filePath)}</location>`);
-        lines.push("  </skill>");
-    }
-    lines.push("</available_skills>");
-    return lines.join("\n");
-}
 /**
  * Load skills from all configured locations.
  * Returns skills and any validation diagnostics.