@yanlinglabs/winter-agent-runtime 0.0.27

package/dist/settings/loaders/mcp-config.d.ts

@@ -0,0 +1,83 @@
+import { type BrandProfile, type McpServerConfig, type ResolvedSettingSource, type SettingSource } from "@yanlinglabs/winter-agent-sdk";
+import type { McpConfigSourceOrigin, McpServerSource } from "../../mcp/lifecycle.js";
+/**
+ * WS-01 §2.4: the native project MCP config, under `brand.projectDirName`. The official branch's
+ * `.mcp.json` is NOT read.
+ */
+export declare function projectMcpConfigRelative(brand?: Pick<BrandProfile, "projectDirName">): string;
+/** Winter's own value, for every caller that has not threaded a brand. */
+export declare const PROJECT_MCP_CONFIG_RELATIVE: string;
+export interface RejectedMcpConfig {
+    origin: McpConfigSourceOrigin;
+    path?: string;
+    reason: string;
+}
+export interface McpConfigLoadResult {
+    sources: McpServerSource[];
+    rejected: RejectedMcpConfig[];
+}
+/** One settings tier's contribution -- the same input shape `buildHookEntriesFromSettings` accepts. */
+export interface SettingsMcpSourceInput {
+    source: ResolvedSettingSource;
+    path?: string;
+    settings?: {
+        mcpServers?: unknown;
+        [key: string]: unknown;
+    };
+    values?: {
+        mcpServers?: unknown;
+        [key: string]: unknown;
+    };
+    policyOrigin?: string;
+    loaded?: boolean;
+    error?: string;
+}
+/**
+ * `<cwd>/.winter/mcp.json`.
+ *
+ * SOURCE-GATED on `project ∈ settingSources`, exactly like project skills and commands: WS-01 §2.4
+ * has the official branch run with `settingSources: []` and get its servers "via explicit
+ * `mcpServers` options only", which is only true if this file is not read in that mode.
+ *
+ * NO PARENT-WALK, unlike skills. The project `mcp.json` names PROCESSES to run, and a walk would let a
+ * config committed several directories above the session's cwd start a stdio server the user never
+ * looked at. The skills walk carries no such authority. Disclosed divergence from the skill tier.
+ */
+export declare function loadProjectMcpConfig(opts: {
+    cwd: string;
+    settingSources?: SettingSource[] | undefined;
+    brand?: Pick<BrandProfile, "projectDirName">;
+}): McpConfigLoadResult;
+/**
+ * `Settings.mcpServers` from every loaded tier.
+ *
+ * ORDER: the caller's tier order is preserved, and `resolveMcpServerSources` processes by ORIGIN
+ * first, so ordering within an origin is all this controls. Pass the tiers highest-precedence first
+ * (which is the order `resolveSettingsDetailed` already returns them in), and pass this result
+ * BEFORE `loadProjectMcpConfig`'s so a project settings.json entry outranks the ambient
+ * the project `mcp.json` while still sharing its gate.
+ */
+export declare function settingsMcpServerSources(perSource: readonly SettingsMcpSourceInput[] | undefined): McpConfigLoadResult;
+export interface GlobalConfigMcpInput {
+    /** The shared runtime home (`sdkHomeOf(WINTER_HOME)`), where `.winter.json` lives. */
+    home: string;
+    cwd: string;
+    /** The canonical git root, or `null` outside a repository -- the caller's own resolution (see header). */
+    gitRoot: string | null;
+    brand: Pick<BrandProfile, "homeDirName">;
+    sources: readonly SettingSource[];
+}
+export interface GlobalConfigMcpResult {
+    user: Record<string, McpServerConfig>;
+    /** This checkout's `projects[<key>].mcpServers` only -- never another project's entry in the same file. */
+    local: Record<string, McpServerConfig>;
+    /**
+     * NOT in the plan brief's sketch interface, added here for the same reason every other loader in
+     * this file carries one: "a malformed file produces a scan error, not a throw" (the brief's own
+     * L1a.5 test list) needs somewhere to put that scan error. `RejectedMcpConfig` already exists for
+     * exactly this shape, so this is the minimal extension rather than a second, parallel error
+     * channel.
+     */
+    rejected: RejectedMcpConfig[];
+}
+export declare function loadGlobalConfigMcp(input: GlobalConfigMcpInput): GlobalConfigMcpResult;

package/dist/settings/loaders/plugin-mcp.d.ts

@@ -0,0 +1,3 @@
+import type { McpServerSource } from "../../mcp/lifecycle.js";
+import type { PluginBundle } from "../../plugins/bundle.js";
+export declare function pluginMcpServerSources(bundles: readonly PluginBundle[]): McpServerSource[];

package/dist/settings/loaders/strict-plugin-only.d.ts

@@ -0,0 +1,13 @@
+/** The pinned area names. An unrecognised string in the array is ignored, never treated as `true`. */
+export type StrictPluginOnlyArea = "skills" | "agents" | "hooks" | "mcp";
+export type StrictPluginOnlyCustomization = boolean | readonly string[];
+/**
+ * Does the setting restrict `area` to plugin-sourced customization only?
+ *
+ * `true` restricts every area; an array restricts exactly the areas it names; `false`/absent/an
+ * empty array restrict nothing. A non-array, non-boolean value (a settings file is JSON and may
+ * carry anything) restricts nothing -- the fail-OPEN direction is correct here because this setting
+ * REMOVES capability: reading a malformed value as "restrict everything" would silently delete a
+ * user's whole skills directory from the session over a typo.
+ */
+export declare function isStrictPluginOnly(value: StrictPluginOnlyCustomization | undefined, area: StrictPluginOnlyArea): boolean;

package/dist/settings/resolve.d.ts

@@ -0,0 +1,2 @@
+export { resolveSettings, resolveSettingsDetailed, filterEscalatingDefaultMode, applyWorkspaceTrust, settingsPathFor, loadSettingsFile, SETTING_SOURCES, OVERLAY_NEVER_KEYS, ESCALATING_PERMISSION_MODES, PROJECT_PERMISSIVE_KEYS, providerSettingsFrom, } from "@yanlinglabs/winter-agent-sdk";
+export type { SettingSource, ResolvedSettingSource, PolicySettingsOrigin, Settings, SettingsPermissionsBlock, SettingsHooksConfig, SettingsHookMatcherGroup, SettingsHookHandler, ProvenanceEntry, ResolvedSettings, ResolvedSettingsSourceEntry, ResolveSettingsOptions, DetailedResolvedSettings, DetailedSettingsSourceEntry, ResolveSettingsDetailedOptions, WorkspaceTrustFilterOptions, } from "@yanlinglabs/winter-agent-sdk";

package/dist/settings/sources.d.ts

@@ -0,0 +1,2 @@
+export { settingsPathFor, loadSettingsFile, SETTING_SOURCES } from "@yanlinglabs/winter-agent-sdk";
+export type { SettingSource, SettingsPathOptions, LoadedSettingsFile, Settings } from "@yanlinglabs/winter-agent-sdk";

package/dist/settings/trust.d.ts

@@ -0,0 +1,36 @@
+import type { RuntimeConfig } from "@yanlinglabs/winter-agent-sdk";
+/**
+ * Two reasons, not four.
+ *
+ * The Task 2 brief's union also carried `"project-source-selected"` and
+ * `"captured-no-trust-concept"` — the two outcomes R5-6 was hedging between. Capture (1)
+ * DISCRIMINATED, and neither is reachable: selecting `'project'` is not trust, and the pin does have
+ * a trust concept. They are removed rather than left as dead members a lane might one day produce,
+ * which would be a verdict no consumer could act on. Narrowing here is a deliberate divergence from
+ * the brief's literal type, recorded in the Task 2 report.
+ */
+export type TrustVerdictReason = "host-declared" | "untrusted-default";
+export interface TrustVerdict {
+    trusted: boolean;
+    reason: TrustVerdictReason;
+}
+/**
+ * The seam engine.ts consults. `cwd` is part of the signature because a HOST-supplied source may
+ * legitimately vary by directory (a daemon that remembers which repositories a user has approved);
+ * Winter's own `defaultTrustSource` deliberately does not, per the capture.
+ */
+export interface WorkspaceTrustSource {
+    verdict(cwd: string): TrustVerdict;
+}
+/**
+ * The default source: trusted iff the host explicitly declared `trustedWorkspace: true`.
+ *
+ * `settingSources` is in the parameter type and is deliberately NOT read — the signature keeps it so
+ * a future host-side source can see what the session selected, and so the ONE thing capture (1)
+ * rules out (inferring trust from source selection) is visibly not done rather than merely absent.
+ * An exact `=== true` check, never a truthy coercion: this value crosses a JSON wire, where a
+ * `"false"` string would otherwise grant trust.
+ */
+export declare function defaultTrustSource(config: Pick<RuntimeConfig, "settingSources" | "trustedWorkspace">): WorkspaceTrustSource;
+/** A constant source, for tests and for a host that has already made the decision elsewhere. */
+export declare function fixedTrustSource(trusted: boolean): WorkspaceTrustSource;

package/dist/skills/attachment.d.ts

@@ -0,0 +1,25 @@
+import type { SkillTier } from "./loader.js";
+/** The entry name. One constant, so a future dialect entry and this producer cannot disagree. */
+export declare const INVOKED_SKILLS_ATTACHMENT_TYPE = "invoked_skills";
+export interface InvokedSkillEntry {
+    /** The skill's PRIMARY identity, not the alias the model happened to type. */
+    name: string;
+    source: SkillTier;
+    /** Absolute path of the SKILL.md whose body entered the conversation. */
+    path: string;
+    /** The contributing plugin, present iff `source === "plugin"`. */
+    plugin?: string;
+    /** The invocation's `args`, omitted entirely when none were given. */
+    args?: string;
+    /** Size of the body AS DELIVERED -- post byte-cap, so it reflects what the model actually received. */
+    bodyBytes: number;
+}
+export interface InvokedSkillsAttachment {
+    type: typeof INVOKED_SKILLS_ATTACHMENT_TYPE;
+    skills: InvokedSkillEntry[];
+}
+/**
+ * An attachment carries an ARRAY even for a single invocation: a turn may invoke several skills, and
+ * a consumer that folds attachments should never have to distinguish "one" from "several".
+ */
+export declare function invokedSkillsAttachment(skills: InvokedSkillEntry[]): InvokedSkillsAttachment;

package/dist/skills/frontmatter.d.ts

@@ -0,0 +1,64 @@
+/** WS-11 §2.5's jail, verbatim: lowercase alnum + dash, 1-64 chars, no separators/dots/underscores/uppercase. */
+export declare const SKILL_NAME_PATTERN: RegExp;
+/**
+ * A PLUGIN name may additionally carry the leading dot the canonical project plugin has
+ * (the project dot-dir, WS-01 §2.4 / WS-11 §4) -- so the qualified form `<projectDir>:<skill>` is expressible.
+ * Otherwise the same jail: no path separators, no `..`, no whitespace.
+ */
+export declare const PLUGIN_NAME_PATTERN: RegExp;
+/** Norma parity: the body cap applied at LOAD time (never at index time -- bodies are not read at index time at all). */
+export declare const DEFAULT_SKILL_BODY_BYTES = 32768;
+/**
+ * WINTER ADDITION, disclosed: a description byte cap applied at PARSE time so a pathological
+ * SKILL.md cannot grow the in-memory index without bound. Deliberately far above
+ * `skillListingMaxDescChars`' pinned default of 1536 CHARS (listing.ts), so the observable listing
+ * is decided by that cap and never by this one -- this bounds memory, not presentation.
+ */
+export declare const DEFAULT_SKILL_DESCRIPTION_BYTES = 4096;
+/** Norma parity, byte-for-byte. */
+export declare const SKILL_TRUNCATION_MARKER = "\n[\u2026truncated]";
+/**
+ * `null` when the name is a legal slug; an error string otherwise.
+ *
+ * WHEN IT RUNS, precisely (fix round 1, corrected -- this used to say "before any fs op", which is
+ * true of only one of the two callers): on the EXECUTOR path (`isLegalSkillIdentity`) it runs before
+ * anything touches the filesystem, because the name comes from the model. On the INDEX path
+ * (`SkillIndex.build`) the SKILL.md has already been read by then -- the jail is applied to the
+ * RESOLVED name, which may come from the file's own `name:` frontmatter and so cannot be known
+ * earlier. That is safe because the PATH the index reads is always built from `readdirSync` output,
+ * never from a declared name; the jail's job there is to keep an escaping declared name out of the
+ * index, not to protect the read.
+ */
+export declare function skillNameError(name: string): string | null;
+/** `null` when the plugin name is legal (the leading-dot form included). */
+export declare function pluginNameError(name: string): string | null;
+export interface ParsedSkillFile {
+    name: string;
+    description: string;
+    body: string;
+    /** Winter extension (WS-11 §2.5): the `author:` stamp `self`-tier skills carry. */
+    author?: string;
+}
+/**
+ * Cap `s` to `maxBytes` UTF-8 bytes on a byte boundary, appending the truncation marker when cut.
+ * Norma's `capBytes`, unchanged -- including the deliberate detail that `subarray` may split a
+ * multi-byte sequence, which `toString("utf8")` then renders as a replacement character rather than
+ * throwing. A byte cap that silently became a character cap would stop bounding memory.
+ */
+export declare function capBytes(s: string, maxBytes: number): string;
+/**
+ * Parse a SKILL.md's raw text. `null` for anything that is not a usable skill: no leading fence, or
+ * an unterminated fence.
+ *
+ * WS-21 §6.3 items 9-10 (claude's `getSkillCommandName`, measured 2026-09-23): a skill's IDENTITY is
+ * always the directory it was discovered under -- `fallbackName` -- never a frontmatter `name:` key.
+ * Earlier this parser let a declared `name:` override the directory, which meant a checked-in
+ * SKILL.md could claim any identity a caller had not yet validated; now the frontmatter's `name:`
+ * line, if present, is not even read. A missing `description:` no longer invalidates the file either
+ * -- it yields `""` and the skill is kept (claude does not drop undescribed skills; the model still
+ * sees the name, and `renderSkillListingLine` already prints a name-only line for an empty
+ * description).
+ *
+ * The fence must start at byte 0 -- a `---` deeper in the file is body text, never frontmatter.
+ */
+export declare function parseSkillFile(raw: string, fallbackName: string): ParsedSkillFile | null;

package/dist/skills/index.d.ts

@@ -0,0 +1,16 @@
+export { DEFAULT_SKILL_BODY_BYTES, DEFAULT_SKILL_DESCRIPTION_BYTES, SKILL_NAME_PATTERN, SKILL_TRUNCATION_MARKER, capBytes, parseSkillFile, pluginNameError, skillNameError } from "./frontmatter.js";
+export type { ParsedSkillFile } from "./frontmatter.js";
+export { SELF_SUBDIR, SKILL_METADATA_PREFIX_BYTES, ABSENT_SKILL_FILE, findRepoRoot, projectSkillRoots, readSkillMetadata, scanSkillRoot, scanUserSkillRoot } from "./loader.js";
+export type { DiscoveredSkill, SkillMetadataRead, SkillScanError, SkillScanResult, SkillTier } from "./loader.js";
+export { PROJECT_PLUGIN_NAME, SkillIndex } from "./store.js";
+export type { PluginSkillContribution, SkillIndexOptions, SkillMeta } from "./store.js";
+export { DEFAULT_SKILL_LISTING_BUDGET_FRACTION, DEFAULT_SKILL_LISTING_MAX_DESC_CHARS, LISTING_TRUNCATION_SUFFIX, SKILL_LISTING_CHARS_PER_TOKEN, DEFAULT_SKILL_LISTING_CONTEXT_WINDOW_TOKENS, buildSkillListing, isModelVisible, renderSkillListingContent, renderSkillListingLine, truncateSkillDescription, isUserInvocable, skillListingBudgetChars, } from "./listing.js";
+export type { BuildSkillListingOptions, SkillOverride, SkillOverrides } from "./listing.js";
+export { SKILL_TOOL_NAME, autoSkillPermissionEntries, isLegalSkillIdentity, isSkillEnabled, validateSkillsOption } from "./option.js";
+export type { SkillsOptionFailure, SkillsOptionSuccess, SkillsOptionValidation, ValidateSkillsOptions } from "./option.js";
+export { matchesSkillRule, parseSkillRule, skillRulesAllow } from "./permission-rules.js";
+export type { SkillRuleTarget } from "./permission-rules.js";
+export { INVOKED_SKILLS_ATTACHMENT_TYPE, invokedSkillsAttachment } from "./attachment.js";
+export type { InvokedSkillEntry, InvokedSkillsAttachment } from "./attachment.js";
+export { clearSkillSessionRuntime, getSkillSessionRuntime, registerSkillSessionRuntime } from "./runtime.js";
+export type { SkillSessionRuntime } from "./runtime.js";

package/dist/skills/listing.d.ts

@@ -0,0 +1,89 @@
+import type { SkillListing } from "../context/seam.js";
+import type { SkillMeta } from "./store.js";
+/** `sdk.d.ts:5499`'s doc-stated default. */
+export declare const DEFAULT_SKILL_LISTING_MAX_DESC_CHARS = 1536;
+/** `sdk.d.ts:5503`'s doc-stated default: the fraction of the context window reserved for the listing. */
+export declare const DEFAULT_SKILL_LISTING_BUDGET_FRACTION = 0.01;
+/**
+ * WINTER-DEFINED, disclosed: the budget setting is a fraction of a TOKEN window, and this producer
+ * measures CHARACTERS. 4 chars/token is the conventional English-text approximation and is used
+ * only to size a budget -- nothing downstream treats it as a real tokenizer, and the accountant
+ * (T2's `ContextAccountant`) remains the only thing that counts real tokens. A caller that knows
+ * better passes `budgetChars` directly and this constant is not consulted.
+ */
+export declare const SKILL_LISTING_CHARS_PER_TOKEN = 4;
+/** Appended to a description cut by `maxDescChars`. One character, so it barely moves the budget. */
+export declare const LISTING_TRUNCATION_SUFFIX = "\u2026";
+/**
+ * `Settings.skillOverrides` (`sdk.d.ts:5651`) -- four states of per-skill visibility.
+ *
+ * `on` (or absent): listed to the model and invocable.
+ * `name-only`: listed WITHOUT its description (the model sees it exists; the description costs nothing).
+ * `user-invocable-only`: not listed to the model at all, but still resolvable by a user `/name`.
+ * `off`: invisible and uninvocable.
+ */
+export type SkillOverride = "on" | "name-only" | "user-invocable-only" | "off";
+/** Open-valued on purpose: a settings file is JSON and may carry a state a newer engine defines. */
+export type SkillOverrides = Readonly<Record<string, string>>;
+export interface BuildSkillListingOptions {
+    maxDescChars?: number | undefined;
+    budgetFraction?: number | undefined;
+    contextWindowTokens?: number | undefined;
+    /** An explicit character budget, bypassing the fraction x window x ratio derivation. `0` disables the budget. */
+    budgetChars?: number | undefined;
+    skillOverrides?: SkillOverrides | undefined;
+}
+/**
+ * True when the model may see this skill in the listing. An UNRECOGNISED override value reads as
+ * `on`: a settings file written for a newer engine must never silently hide a skill on an older one
+ * (the same "accepted, preserved, inert" posture WS-08 §1 pins for unknown hook event names).
+ */
+export declare function isModelVisible(overrides: SkillOverrides | undefined, skill: SkillMeta | string): boolean;
+/** True when a USER `/name` may still reach this skill. Only `off` closes that door. */
+export declare function isUserInvocable(overrides: SkillOverrides | undefined, skill: SkillMeta | string): boolean;
+/**
+ * claude's `Ckn`: the context window a budget is sized against when the session reports none.
+ */
+export declare const DEFAULT_SKILL_LISTING_CONTEXT_WINDOW_TOKENS = 200000;
+/**
+ * The whole-listing character budget -- claude's `Ige`: `floor(window x chars-per-token x fraction)`,
+ * with claude's 200k-token default window when the session reports none (or a non-finite one).
+ * An explicit `budgetChars` wins (claude's `SLASH_COMMAND_TOOL_CHAR_BUDGET` analog), and there `0`
+ * means "no budget" -- a Winter extension, never "no listing".
+ */
+export declare function skillListingBudgetChars(opts: {
+    contextWindowTokens?: number | undefined;
+    budgetFraction?: number | undefined;
+    budgetChars?: number | undefined;
+}): number;
+/**
+ * claude's `xkn`: a description longer than the cap keeps `cap - 1` characters and gains the
+ * ellipsis, so the result is exactly `cap` characters long.
+ */
+export declare function truncateSkillDescription(description: string, maxDescChars: number): string;
+/**
+ * claude's per-skill line (`Mkn`): `- <name>: <description>`, or `- <name>` for an entry whose
+ * description is empty (a `name-only` override, or one the budget reduced to its name).
+ */
+export declare function renderSkillListingLine(entry: {
+    name: string;
+    description: string;
+}): string;
+/** The `skill_listing` attachment's `content`: one line per entry, newline-joined (claude's `Rot` output). */
+export declare function renderSkillListingContent(entries: readonly {
+    name: string;
+    description: string;
+}[]): string;
+/**
+ * Build the model-facing listing -- claude 0.3.250's `Rot`, applied here once so every consumer sees
+ * the budgeted result.
+ *
+ * ORDER IS PRECEDENCE ORDER (the index's own): project first, builtin last. Every visible skill is
+ * listed; the budget decides only which ones keep their DESCRIPTION:
+ *   - everything fits -> every line is full;
+ *   - over budget -> `name-only` entries and Winter's builtin (claude: bundled) skills stay full,
+ *     every other entry starts as its bare name, and descriptions are restored in priority order
+ *     while the remaining budget holds them. claude orders that priority by its per-skill usage
+ *     score; Winter keeps no usage history, so every score ties and precedence order decides.
+ */
+export declare function buildSkillListing(skills: readonly SkillMeta[], opts?: BuildSkillListingOptions): SkillListing;

package/dist/skills/loader.d.ts

@@ -0,0 +1,104 @@
+import { type BrandProfile } from "@yanlinglabs/winter-agent-sdk";
+import { type ParsedSkillFile } from "./frontmatter.js";
+/** WS-11 §2.1's tier table, and `SkillListing["source"]` (context/seam.ts, R5-17) verbatim. */
+export type SkillTier = "project" | "user" | "plugin" | "builtin" | "self";
+export interface DiscoveredSkill {
+    /** The INVOCABLE name. Plugin skills arrive here already qualified `<plugin>:<skill>` (store.ts). */
+    name: string;
+    description: string;
+    source: SkillTier;
+    /** Absolute path of the SKILL.md this was discovered from. */
+    path: string;
+    /** Winter extension (WS-11 §2.5). */
+    author?: string;
+    /** Present iff `source === "plugin"` -- the contributing plugin's name. */
+    plugin?: string;
+}
+/** One SKILL.md that could not become an index entry -- surfaced, never silently dropped (A-11). */
+export interface SkillScanError {
+    /** The immediate subdirectory of the scanned root -- what an author would go and look at. */
+    directory: string;
+    /** Absolute path of the SKILL.md. */
+    path: string;
+    source: SkillTier;
+    reason: string;
+}
+export interface SkillScanResult {
+    skills: DiscoveredSkill[];
+    errors: SkillScanError[];
+}
+/** The reserved subdirectory of the user root that holds agent-authored skills (Norma parity). */
+export declare const SELF_SUBDIR = "self";
+/**
+ * THE INDEX-TIME READ BOUND (fix wave, A-11 / T5 review Nit 5).
+ *
+ * `SkillIndex.build()` used to `readFileSync` every SKILL.md in full and drop the parsed body --
+ * "lazy" meant NOT RETAINED, not NOT READ. That read is unconditional and pre-session: it covers
+ * every `<cwd>/.winter/skills/**` up to the repository root, content that arrives with a `git clone`,
+ * before any trust decision and before the model runs. With no cap at all the bound was "the total
+ * bytes of every skill file in the tree" -- a 64 MB SKILL.md cost 64 MB of heap during startup, and
+ * a startup failure is not something a session can route around.
+ *
+ * Frontmatter lives at the HEAD of the file, so a bounded prefix is everything the index needs.
+ * `load()` keeps the full read (bodies are what it exists to fetch), which is the split that makes
+ * this safe: the cap bounds DISCOVERY, never invocation.
+ */
+export declare const SKILL_METADATA_PREFIX_BYTES = 65536;
+/**
+ * The nearest ancestor of `from` (inclusive) that holds a `.git` entry, or `undefined` when there is
+ * none. `.git` may be a DIRECTORY or a FILE (a worktree/submodule gitlink is a file), so existence
+ * is what is checked, never `isDirectory()` -- a session run inside a git worktree must find the
+ * same boundary a session in the main checkout does.
+ */
+export declare function findRepoRoot(from: string): string | undefined;
+/**
+ * WS-11 §2.1 / report §60: "project lookup walks `<projectDir>/skills/` at cwd and parent
+ * directories up to the repository root". NEAREST FIRST -- the returned order IS the precedence
+ * order, so a project skill beside the code shadows one at the repo root.
+ *
+ * With no repository root above `cwd` the walk covers `cwd` ALONE. Climbing to the filesystem root
+ * in that case would let a stray project dot-dir under `/tmp` (or a home directory) silently join a
+ * session started in a scratch directory -- the boundary exists to stop exactly that.
+ *
+ * P7a (D19): the dot-dir is `brand.projectDirName`; omitted = `WINTER_BRAND`, i.e. today's walk.
+ */
+export declare function projectSkillRoots(cwd: string, brand?: Pick<BrandProfile, "projectDirName">): string[];
+/**
+ * Scan `<root>/<dir>/SKILL.md` for every immediate SUBDIRECTORY of `root`. `exclude` skips reserved
+ * subdirectory names (the user root's `self/`, scanned separately as its own tier).
+ *
+ * A directory whose name fails the slug jail is still scanned, not skipped here: a skill's identity
+ * is ALWAYS the directory it was discovered under (`parseSkillFile`'s own `fallbackName`, never a
+ * frontmatter `name:` key -- that field's own header explains why the declared-name-wins behaviour
+ * was retired). Filtering the directory out at scan time would make a jail-failing skill vanish with
+ * no explanation; scanning it and letting store-level validation apply the jail to the resolved name
+ * (store.ts) is what lets A-11's "no silent vanish" rule report WHY it was refused.
+ */
+export declare function scanSkillRoot(root: string, source: SkillTier, exclude?: ReadonlySet<string>): SkillScanResult;
+/** Scan the user root, skipping its reserved `self/` subdirectory. */
+export declare function scanUserSkillRoot(root: string): SkillScanResult;
+/** The one reason `scanSkillRoot` does NOT report: a subdirectory that simply holds no SKILL.md. */
+export declare const ABSENT_SKILL_FILE = "no SKILL.md";
+export type SkillMetadataRead = {
+    ok: true;
+    skill: ParsedSkillFile;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Read one SKILL.md's METADATA. Shared by `scanSkillRoot` above and by store.ts's `load()`, so the
+ * frontmatter contract is applied exactly once.
+ *
+ * `opts.maxBytes` reads only that many bytes from the head of the file (A-11): the frontmatter is at
+ * the top, so the index never pays for a body it is about to drop. WITHOUT it the whole file is
+ * read, which is what `load()` wants and needs.
+ *
+ * A RESULT, not `null`, because the two failures are not the same fact: "this is not a skill" and
+ * "this skill could not be read" both used to disappear identically, which is precisely the silent
+ * vanish A-11 is about. A prefix read that finds an unclosed fence says so, naming the bound, rather
+ * than reporting the file as unparseable -- it may be perfectly valid and merely enormous.
+ */
+export declare function readSkillMetadata(path: string, fallbackName: string, opts?: {
+    maxBytes?: number;
+}): SkillMetadataRead;

package/dist/skills/option.d.ts

@@ -0,0 +1,68 @@
+import type { SkillsOption } from "@yanlinglabs/winter-agent-sdk";
+import type { SkillIndex } from "./store.js";
+/** The one tool every skill is invoked through (WS-11 §2.3 -- never one tool per skill). */
+export declare const SKILL_TOOL_NAME = "Skill";
+export interface SkillsOptionSuccess {
+    ok: true;
+    /** The caller's names, order preserved, unresolved aliases left exactly as written. */
+    skills: string[];
+    warnings: string[];
+}
+export interface SkillsOptionFailure {
+    ok: false;
+    unknown: string[];
+    message: string;
+    warnings: string[];
+}
+export type SkillsOptionValidation = SkillsOptionSuccess | SkillsOptionFailure;
+export interface ValidateSkillsOptions {
+    /**
+     * An explicit BUILT-IN RESTRICTION list -- `AgentDefinition.tools` for a child, or a host's own
+     * equivalent for the main session. An EMPTY array is treated as "no restriction", matching
+     * `validateAgentDefinition`'s existing reading in subagents/definitions.ts.
+     */
+    tools?: readonly string[] | undefined;
+    /** `Options.disallowedTools` -- the other way to make the Skill tool unreachable. */
+    disallowedTools?: readonly string[] | undefined;
+}
+/**
+ * Validate the option against a built index.
+ *
+ * `undefined` and `"all"` both mean "every indexed skill" (capture (4): omitting the option is NOT
+ * "skills off"); `[]` means "none", which is a legitimate, validated configuration and NOT the same
+ * thing as omission.
+ */
+export declare function validateSkillsOption(skills: SkillsOption | undefined, index: SkillIndex, opts?: ValidateSkillsOptions): SkillsOptionValidation;
+/**
+ * Is `name` invocable under this session's `skills` option?
+ *
+ * Alias-aware in BOTH directions: an option listing `.winter:review` enables an invocation of
+ * `review`, and vice versa. Without that, the two spellings of one skill would disagree about
+ * whether it is enabled, which is the drift WS-11 §4's "permission rules match identically across
+ * branches" exists to prevent (permission-rules.ts carries the same obligation for rules).
+ */
+export declare function isSkillEnabled(skills: SkillsOption | undefined, name: string, index: SkillIndex): boolean;
+/**
+ * The permission entries the ENGINE adds when `skills` is set -- WS-11 §2.2: "callers do not add
+ * them to `allowedTools`".
+ *
+ * Rule strings, not `PermissionRuleValue` objects, because `RuntimeConfig.allowedTools` /
+ * `permissions.allow` are both `string[]` and that is where these land.
+ *
+ * `"all"` produces the BARE tool rule (`Skill`), which grammar.ts already treats as matching every
+ * call regardless of input -- exactly the intended meaning, and it stays one entry however many
+ * skills are installed. A list produces one name-scoped rule each; matching those against a live
+ * invocation is permission-rules.ts's job (grammar.ts cannot do it today -- see that file's header).
+ */
+export declare function autoSkillPermissionEntries(skills: SkillsOption | undefined): string[];
+/**
+ * A name is rejected before it ever reaches the filesystem if it is not a legal identity: a bare
+ * slug, or `<plugin>:<slug>`. Used by the executor, which receives its name from the MODEL and must
+ * not hand an arbitrary string to a path join.
+ *
+ * The plugin half uses `pluginNameError`, THE SAME JAIL `SkillIndex.build` admits plugin names by --
+ * not a stricter one. Two jails that disagree produce a skill the index advertises and the executor
+ * refuses: `PLUGIN_NAME_PATTERN` admits any leading-dot name, so a plugin named `.acme` indexes
+ * `.acme:ship`, and a check that special-cased only the project dot-dir would reject it at invocation.
+ */
+export declare function isLegalSkillIdentity(name: string): boolean;

package/dist/skills/permission-rules.d.ts

@@ -0,0 +1,21 @@
+/** The invocation, reduced to what a rule can see. `identities` is `SkillIndex.identities(name)`. */
+export interface SkillRuleTarget {
+    identities: readonly string[];
+    args?: string | undefined;
+}
+/**
+ * Parse a rule STRING into its Skill content, or `undefined` when the rule is not a Skill rule at
+ * all. A bare `Skill` yields `{ content: undefined }` -- the match-everything form, matching
+ * grammar.ts's own `isBareEquivalent` reading of a bare tool name.
+ */
+export declare function parseSkillRule(raw: string): {
+    content: string | undefined;
+} | undefined;
+/**
+ * Does `content` (a `Skill(...)` rule's raw inner text) match this invocation?
+ *
+ * `undefined` content (a bare `Skill` rule) and a literal `*` both match everything.
+ */
+export declare function matchesSkillRule(content: string | undefined, target: SkillRuleTarget): boolean;
+/** True when ANY rule in the list is a Skill rule matching this invocation. Non-Skill rules are ignored. */
+export declare function skillRulesAllow(rules: readonly string[] | undefined, target: SkillRuleTarget): boolean;

package/dist/skills/runtime.d.ts

@@ -0,0 +1,21 @@
+import type { SkillsOption } from "@yanlinglabs/winter-agent-sdk";
+import type { InvokedSkillsAttachment } from "./attachment.js";
+import type { SkillOverrides } from "./listing.js";
+import type { SkillIndex } from "./store.js";
+export interface SkillSessionRuntime {
+    index: SkillIndex;
+    /** This session's `Options.skills`. Absent means every indexed skill (capture (4)). */
+    skills?: SkillsOption | undefined;
+    /** `Settings.skillOverrides` for this session. */
+    skillOverrides?: SkillOverrides | undefined;
+    /**
+     * The attachment SINK. Absent is legitimate (a host that does not persist attachments), and the
+     * executor still returns the body -- the attachment is a record of the invocation, never a
+     * precondition for it. A throwing sink must never fail the tool call, so the executor guards it.
+     */
+    onInvoked?: ((attachment: InvokedSkillsAttachment) => void) | undefined;
+}
+export declare function registerSkillSessionRuntime(key: string, runtime: SkillSessionRuntime): void;
+export declare function getSkillSessionRuntime(key: string): SkillSessionRuntime | undefined;
+/** Called on run teardown. A registry that only ever grows would leak an index per session. */
+export declare function clearSkillSessionRuntime(key: string): void;