@yanlinglabs/winter-agent-runtime 0.0.27

package/dist/permissions/protected.d.ts

@@ -0,0 +1,54 @@
+import { type BrandProfile } from "@yanlinglabs/winter-agent-sdk";
+/**
+ * P7a (D19): the three brand fields the protected-path floor needs.
+ *
+ * A `Pick`, and OPTIONAL at every entry point, for the same reason as everywhere else in this
+ * sweep: ~30 hand-built contexts in this package's tests call these primitives directly, and
+ * `WINTER_BRAND` as the default keeps every one of them byte-identical.
+ */
+export type ProtectedBrand = Pick<BrandProfile, "homeDirName" | "projectDirName" | "instructionsFile">;
+export declare const PROTECTED_DIRECTORY_NAMES: ReadonlySet<string>;
+export declare const PROTECTED_FILE_BASENAMES: ReadonlySet<string>;
+/**
+ * True when `absPath` is inside a session's own persisted-workflow-script directory under `home`.
+ *
+ * Takes an ALREADY-ABSOLUTE path (every caller here resolves first) and `home` explicitly -- this
+ * module resolves no environment of its own, matching `isProtectedWrite`'s existing `ctx.home`
+ * contract.
+ */
+export declare function isWorkflowScriptCarveOut(absPath: string, home: string, resolvedWinterHome?: string, brand?: ProtectedBrand): boolean;
+/**
+ * True when `absPath` is inside a project's own auto-memory directory under `home` (SDK 0.0.4).
+ *
+ * Same contract as `isWorkflowScriptCarveOut` one function up -- an ALREADY-ABSOLUTE path, an
+ * explicit `home`, an optional resolved winter root, an optional brand -- and the same two anchors,
+ * for the same Phase-5-I1 reason: `context/memory-key.ts`'s `memoryDirFor` joins onto the RESOLVED
+ * winter home, so a carve-out anchored only at `<osHome>/<homeDirName>` would name a directory the
+ * feature never writes to whenever `<PREFIX>HOME` points elsewhere.
+ */
+export declare function isMemoryCarveOut(absPath: string, home: string, resolvedWinterHome?: string, brand?: ProtectedBrand): boolean;
+/** Is `outputsDir` (absolute) a directory the outputs carve-out may apply to? See the block above. */
+export declare function isCarvableOutputsDir(outputsDir: string, home: string, resolvedWinterHome: string | undefined, brand?: ProtectedBrand): boolean;
+/**
+ * True when `absPath` is strictly inside one of `outputsDirs` (the caller's already-validated forms of
+ * one outputs directory -- its lexical path and its real path) and nothing BELOW that directory is
+ * itself protected.
+ */
+export declare function isOutputsCarveOut(absPath: string, outputsDirs: readonly string[], brand?: ProtectedBrand): boolean;
+export declare function isProtectedWrite(path: string, ctx: {
+    cwd: string;
+    home: string;
+    winterHome?: string;
+    storeHome?: string;
+    brand?: ProtectedBrand;
+    outputsDirs?: readonly string[];
+}): boolean;
+export interface CriticalRemovalResult {
+    critical: boolean;
+    reason?: string;
+}
+export declare function isCriticalRemoval(command: string, ctx: {
+    cwd: string;
+    home: string;
+    additionalDirectories?: string[];
+}): CriticalRemovalResult;

package/dist/permissions/ruleset.d.ts

@@ -0,0 +1,134 @@
+import { type ParsedRule } from "./grammar.js";
+import type { PermissionBehavior, PermissionRuleValue, PermissionMode, PermissionUpdate, RuleSource } from "@yanlinglabs/winter-agent-sdk";
+export interface SourcedRuleEntry {
+    rule: ParsedRule;
+    behavior: PermissionBehavior;
+    source: RuleSource;
+    ruleValue: PermissionRuleValue;
+    /**
+     * Fix round 11 ("important" item, claude's own `TFt`/`bl`, dump byte 15441060): the settings
+     * SOURCE's own directory, for a SINGLE-`/`-anchored pattern's root (`resolveFileRuleAnchor`'s own
+     * `/`-branch, file-rules.ts -- already fully wired to consume this, INERT_ANCHOR when absent, a
+     * pre-existing disclosed gap this field closes). Populated ONLY by `buildSettingsRuleSeed`
+     * (production-wiring.ts, the one non-router host with a real settings-file path per tier,
+     * `tier.path`'s own directory) -- every other `sourceRule(...)` call site in this codebase (every
+     * test helper, every Options/canUseTool/plugin-permissions door) omits it, leaving a `/`-anchored
+     * rule from those doors exactly as inert as it always was. Disclosed as low real-world priority
+     * (the controller's own words: "it's inert under the router" -- the router-mediated production
+     * topology this codebase actually ships on does not exercise multiple distinct settings-file
+     * directories the way a bare-CLI/non-router host reading several tiers off disk directly would).
+     */
+    sourceDir?: string;
+}
+export interface SourcedRuleSet {
+    entries: SourcedRuleEntry[];
+    mode?: {
+        value: PermissionMode;
+        source: RuleSource;
+    };
+    directories: Array<{
+        path: string;
+        source: RuleSource;
+    }>;
+}
+export declare function emptyRuleSet(): SourcedRuleSet;
+export declare class PermissionRuleValidationError extends Error {
+    readonly rule: PermissionRuleValue;
+    readonly behavior: PermissionBehavior;
+    constructor(message: string, rule: PermissionRuleValue, behavior: PermissionBehavior);
+}
+export declare class PermissionUpdateAuthorityError extends Error {
+    readonly authority: RuleSource;
+    readonly destination: string;
+    constructor(message: string, authority: RuleSource, destination: string);
+}
+/**
+ * Phase 5 fix wave, C1: EXPORTED so `production-wiring.ts` builds settings-file entries through the
+ * SAME raw-string parse `buildSdkSourcedEntries` uses. A second copy of "how a rule string becomes a
+ * PermissionRuleValue" is exactly the producer/consumer drift this module exists to prevent.
+ */
+export declare function rawToRuleValue(raw: string): PermissionRuleValue;
+export declare function sourceRule(value: PermissionRuleValue, behavior: PermissionBehavior, source: RuleSource, sourceDir?: string): SourcedRuleEntry;
+export declare function applyPermissionUpdate(set: SourcedRuleSet, update: PermissionUpdate, opts: {
+    authority: RuleSource;
+}): SourcedRuleSet;
+export declare function resolveRules(set: SourcedRuleSet, call: {
+    toolName: string;
+    input: Record<string, unknown>;
+}, opts: {
+    trustedWorkspace: boolean;
+    allowManagedPermissionRulesOnly?: boolean;
+}): {
+    deny?: SourcedRuleEntry;
+    ask?: SourcedRuleEntry;
+    allow?: SourcedRuleEntry;
+};
+export declare function effectiveDirectories(set: SourcedRuleSet, opts: {
+    trustedWorkspace: boolean;
+}): string[];
+export interface SdkOptionsRuleInputs {
+    allowedTools?: string[];
+    disallowedTools?: string[];
+    permissions?: {
+        allow?: string[];
+        ask?: string[];
+        deny?: string[];
+    };
+}
+export declare function buildSdkSourcedEntries(opts: SdkOptionsRuleInputs): SourcedRuleEntry[];
+export declare class PermissionJournalDirError extends Error {
+    constructor(message: string);
+}
+export interface PermissionJournalEnvelope {
+    authority: RuleSource;
+    at: string;
+    update: PermissionUpdate;
+}
+export declare function appendPermissionJournal(location: {
+    winterHome: string;
+    projectKey: string;
+    sessionId: string;
+}, update: PermissionUpdate, opts: {
+    authority: RuleSource;
+}): void;
+export interface HookAuditJournalRecord {
+    hookId: string;
+    hookName?: string;
+    hookEvent: string;
+    sessionId: string;
+    uuid: string;
+    toolUseID?: string;
+    requestId?: string;
+    outcome: string;
+    decision?: string;
+    durationMs?: number;
+    agentID?: string;
+}
+export interface HookAuditJournalEnvelope {
+    kind: "hookAudit";
+    at: string;
+    entry: HookAuditJournalRecord;
+}
+export declare function appendHookAuditJournal(location: {
+    winterHome: string;
+    projectKey: string;
+    sessionId: string;
+}, entry: HookAuditJournalRecord): void;
+/** One hook invocation, as the journal recorded it. `at` is the envelope's own ISO timestamp. */
+export interface HookAuditEntry extends HookAuditJournalRecord {
+    at: string;
+}
+/**
+ * Every hook invocation this session journalled, oldest first.
+ *
+ * `filter` narrows without a second pass over the file -- `event` and `outcome` are the two axes an
+ * operator actually asks about ("did my PreToolUse hooks run", "what failed").
+ */
+export declare function readHookAuditJournal(location: {
+    winterHome: string;
+    projectKey: string;
+    sessionId: string;
+}, filter?: {
+    event?: string;
+    outcome?: string;
+}): HookAuditEntry[];

package/dist/permissions/shell-structure.d.ts

@@ -0,0 +1,41 @@
+export interface HeredocExtraction {
+    /** The command with every here-document body (and its delimiter line) and every comment removed. */
+    text: string;
+    /** Bodies of UNQUOTED here-documents: bash expands `$(…)` and backticks inside them. */
+    liveBodies: string[];
+}
+/**
+ * Removes here-document bodies (and comments) from `command`, returning the remaining text and the
+ * bodies bash will still expand. Bodies are removed BEFORE line continuations are joined: a QUOTED
+ * here-document's body is literal (`\<newline>` is not a continuation there), and joining first could
+ * shift its delimiter so that a later line -- `> /etc/passwd` -- was swallowed into the body and never
+ * seen (claude's `extractOutputRedirections` documents that exact attack).
+ *
+ * This is the one scanner that DROPS text, so it follows bash's contexts closely enough never to drop
+ * a command bash runs: `<<` is a here-document only in a command context (not inside `((…))`,
+ * `$((…))`, `$[…]` or `${…}`, where it is a shift or a literal), and `#` is a comment only at the start
+ * of a word in a command context -- ending at a backtick body's closing backtick, as bash's does.
+ */
+export declare function extractHeredocs(command: string): HeredocExtraction | null;
+/**
+ * The bodies of every command-running construct directly inside `text`: `$(…)`, backticks, `(…)`
+ * subshells, and `<(…)` / `>(…)` process substitutions (bash, so `=(…)` is an array, not zsh's
+ * process substitution). `doubleQuoted` scans text bash treats
+ * like the inside of double quotes (an unquoted here-document body), where only `$(…)` and backticks
+ * run. Null when a construct is not closed.
+ */
+export declare function substitutionBodies(text: string, doubleQuoted?: boolean): string[] | null;
+/**
+ * Every simple command `command` runs -- its top-level subcommands and, recursively, the bodies of
+ * its subshells, brace groups, command/process substitutions and unquoted here-documents -- each with
+ * any compound-statement keyword head removed. Null when `command` cannot be analysed.
+ */
+export declare function flattenSubcommands(command: string): string[] | null;
+/** True when `command` contains a process substitution (`<(…)` or `>(…)`) outside quotes. */
+export declare function hasProcessSubstitution(command: string): boolean;
+/**
+ * A command the scanners could NOT parse, split naively -- at every separator and substitution
+ * opener, quotes ignored. Over-approximate by design: only for checks that must see a command
+ * anyway (a deny rule, the critical-removal breaker), where an extra piece can only add a match.
+ */
+export declare function naiveCommandPieces(command: string): string[];

package/dist/plugins/bundle.d.ts

@@ -0,0 +1,100 @@
+import type { InitPluginInfo } from "@yanlinglabs/winter-agent-sdk";
+import type { PluginCommandContribution } from "../commands/resolver.js";
+import type { PluginSkillContribution } from "../skills/store.js";
+import type { PluginAgentDefinition } from "../subagents/definitions.js";
+export interface PluginSkillEntry {
+    /** The BARE name, as the skill's own frontmatter declares it. */
+    name: string;
+    /** `<plugin>:<skill>` -- the one place plugin skills get namespaced (WS-11 §4). */
+    qualifiedName: string;
+    description: string;
+    /** Absolute. */
+    path: string;
+    author?: string;
+}
+export interface PluginCommandEntry {
+    name: string;
+    qualifiedName: string;
+    /** Absolute. */
+    path: string;
+    description?: string;
+    argumentHint?: string;
+}
+export interface PluginMetadata {
+    description?: string;
+    author?: string;
+    homepage?: string;
+    keywords?: string[];
+}
+export interface PluginBundle {
+    /** Manifest `name`, else the root's basename (WS-11 §4's manifestless rule). */
+    name: string;
+    /** The RESOLVED absolute plugin root -- `system/init.plugins[].path`. */
+    path: string;
+    version?: string;
+    /** Absolute path of the manifest that named it, absent for a manifestless plugin. */
+    manifestPath?: string;
+    metadata: PluginMetadata;
+    skills: PluginSkillEntry[];
+    commands: PluginCommandEntry[];
+    /** Keyed by `subagent_type`, each already stamped with this plugin's name. */
+    agents: Record<string, PluginAgentDefinition>;
+    /** The manifest's `hooks` block, verbatim and unparsed. Absent when the plugin declares none. */
+    hooks?: unknown;
+    /** RAW per-name MCP configs (manifest + `.mcp.json`). Empty when `skipMcpDiscovery` is set. */
+    mcpServers: Record<string, unknown>;
+    /** Absolute path of the `.mcp.json` that contributed, when one did. */
+    mcpConfigPath?: string;
+    skipMcpDiscovery: boolean;
+    /**
+     * Absolute path of `<plugin>/output-styles/`, when it exists AND the manifest declares no
+     * `outputStyles` override (mutually exclusive with `outputStylesPaths` below -- see its own
+     * comment, and `workflowsPath`/`workflowsPaths`' identical pairing).
+     */
+    outputStylesPath?: string;
+    /**
+     * WS-21 fix round 5: the manifest's own `outputStyles` key, resolved the same way
+     * `workflowsPaths` is -- present iff the manifest declares the key AND at least one entry
+     * resolved, REPLACING `outputStylesPath` on the key's mere presence regardless of whether
+     * anything resolved. Each entry may be a directory or a single style file.
+     */
+    outputStylesPaths?: string[];
+    /**
+     * Absolute path of `<plugin>/workflows/`, when it exists AND the manifest declares no `workflows`
+     * override (mutually exclusive with `workflowsPaths` below -- see its own comment).
+     */
+    workflowsPath?: string;
+    /**
+     * WS-21 fix round 4 (minors, M-3's last bullet): the manifest's own `workflows` key (`string |
+     * string[]`, `manifest.ts`'s own citation), resolved to absolute paths that exist and do not
+     * escape the plugin root -- present iff the manifest declares the key AND at least one entry
+     * resolved (the pinned binary's own `if(qn.length>0)ve.workflowsPaths=qn`, manifest.ts's
+     * citation). REPLACES `workflowsPath` rather than adding to it, and the replacement fires on the
+     * key's mere PRESENCE, not on whether anything resolved (the pinned binary's `Lt` gate is
+     * `!j.workflows&&...`, checked independently of `qn.length`): a plugin whose every declared entry
+     * is invalid ends up with NEITHER field set, exactly as claude leaves it with no workflows source
+     * at all rather than silently falling back to the shadowed default directory. Each entry may be a
+     * directory or a single workflow file.
+     */
+    workflowsPaths?: string[];
+    /** Absolute path of `<plugin>/bin/`, when it exists. */
+    binPath?: string;
+}
+/**
+ * `system/init.plugins` (`sdk.d.ts:4881-4889`): `{ name, path, version? }`. `version` is
+ * plugin-author-controlled and its own pinned doc says to validate before trusting -- Winter carries
+ * it through verbatim and asserts nothing about it, which is what "carried, not trusted" means here.
+ */
+export declare function pluginInitInfo(bundles: readonly PluginBundle[]): InitPluginInfo[];
+/**
+ * `loadAgentDefinitions`' `pluginAgents` input (subagents/definitions.ts, T2's fourth tier).
+ *
+ * FIRST PLUGIN WINS a name collision, matching `loadPlugins`' own first-wins order for every other
+ * subsystem. The alternative (last wins) would make a plugin's agents depend on where the host
+ * happened to put it in the array, in the opposite direction from skills and commands.
+ */
+export declare function pluginAgentDefinitions(bundles: readonly PluginBundle[]): Record<string, PluginAgentDefinition>;
+/** `SkillIndex.build`'s `plugins` input. BARE names -- the index does the qualification itself. */
+export declare function pluginSkillContributions(bundles: readonly PluginBundle[]): PluginSkillContribution[];
+/** `FilesystemCommandResolver`'s `plugins` input. BARE names, for the same reason. */
+export declare function pluginCommandContributions(bundles: readonly PluginBundle[]): PluginCommandContribution[];

package/dist/plugins/installed.d.ts

@@ -0,0 +1,30 @@
+export interface PluginRecord {
+    /** The `installed_plugins.json` key this record came from -- see the header for why. */
+    id: string;
+    installPath: string;
+    version?: string;
+    scope: "user" | "project" | "local";
+}
+/**
+ * Every installed record, across every key and every scope. Never throws: an absent file, malformed
+ * JSON, or a shape that is not the expected `{plugins: {...}}` object all read as `[]` -- a broken or
+ * missing install ledger must never fail a session's whole plugin load (the same posture
+ * `loadPlugins` takes toward one bad plugin directory).
+ */
+export declare function readInstalledPlugins(pluginsRoot: string): PluginRecord[];
+/**
+ * Every installed record whose id is `true` in `enabled` -- `enabledPlugins` (settings.json's own
+ * field, the same one `manage.ts`'s `setEnabledInSettings` writes). `false`, absent, or a non-boolean
+ * value (`enabledPlugins`' own type also admits `string[]`/an object, claude-native shapes this
+ * build's own management API never writes) all resolve to "not loaded" -- the exact strict-`true`
+ * check `manage.ts`'s own `readEnabledFromSettings` makes, so the two readers of one settings field
+ * can never disagree about which plugins are on.
+ *
+ * SV-4: an enabled key with NO `installed_plugins.json` record falls back to resolving it against a
+ * DIRECTORY marketplace named by the key's own `@<marketplace>` suffix, read in place -- see the
+ * describe block above this function for the full citation. `scope` defaults to `"user"` for a
+ * marketplace-resolved plugin (there is no install record to read a real scope from; `"user"` is
+ * this file's own established fallback for exactly this "nothing to narrow from" case, see
+ * `normalizeScope`).
+ */
+export declare function resolveEnabledPlugins(pluginsRoot: string, enabled: Record<string, boolean> | undefined): PluginRecord[];

package/dist/plugins/loader.d.ts

@@ -0,0 +1,56 @@
+import type { BrandProfile, SdkPluginConfig } from "@yanlinglabs/winter-agent-sdk";
+import type { AgentDefinitionRejection } from "../subagents/definitions.js";
+import type { PluginBundle } from "./bundle.js";
+export type PluginRejectionKind = "unsupported-type" | "missing" | "invalid-manifest" | "invalid-name" | "duplicate";
+export interface RejectedPlugin {
+    /** The path exactly as the caller wrote it -- so a host can match a rejection to its own config entry. */
+    path: string;
+    kind: PluginRejectionKind;
+    reason: string;
+}
+export interface LoadPluginsResult {
+    bundles: PluginBundle[];
+    rejected: RejectedPlugin[];
+    /**
+     * Review r2 finding 2 (whole-branch): rejected `<plugin>/agents/*.md` files -- a broken file
+     * inside an OTHERWISE-loaded plugin (missing/invalid `name:`, missing `description:`) used to
+     * vanish with no channel at all (`scanPluginAgents`'s own former header: "no rejection channel
+     * exists at THIS call site the way `loadAgentDefinitions`'s own `onReject` does"). Distinct from
+     * `rejected` above, which is per-PLUGIN (a whole directory that never became a bundle); this is
+     * per-FILE within a plugin that DID load. `production-wiring.ts` folds these into its own
+     * `warnings` (main.ts's stderr, once per session -- plugin loading runs once).
+     */
+    agentFileRejections: AgentDefinitionRejection[];
+    /**
+     * Fix round 3 (M-5): a `hooks/hooks.json` that exists, parses as an object, but carries no
+     * top-level `"hooks"` key -- claude's own `hook-load-failed` diagnostic (`hooks.json must have
+     * \`hooks\` (the hook matchers) or \`modules\` (hooks modules), or both`, dump-confirmed). The
+     * plugin itself still loads (a malformed hooks file is not a whole-plugin rejection, matching
+     * `agentFileRejections`'s own precedent immediately above), so this is the one channel that ever
+     * names it. `production-wiring.ts` folds these into the same `warnings` list.
+     */
+    hookFileWarnings: string[];
+    /**
+     * WS-21 fix round 4/5 (minors, M-3's last bullet; generalised and renamed in round 5 from
+     * `workflowsPathWarnings` -- ONE fold site, one channel, for every manifest custom-path override
+     * this loader resolves, not a parallel field per component): a manifest `workflows`/`agents`/
+     * `output-styles`/`commands`/`skills` entry that could not be used -- not a string, escapes the
+     * plugin directory (lexically OR through a symlink -- fix round 5's own Aoe/KGe port), does not
+     * exist, or (skills only) is a file where a directory is required -- plus a
+     * `folder-shadowed-by-manifest` notice when an override silently drops an existing default
+     * directory. Named per-plugin, per-entry, on the SAME "recoverable, not a whole-plugin rejection"
+     * footing `hookFileWarnings` above already established for a malformed `hooks.json`.
+     * `production-wiring.ts` folds these into the same `warnings` list too.
+     */
+    manifestPathWarnings: string[];
+}
+/**
+ * Load every configured plugin.
+ *
+ * FIRST OCCURRENCE WINS throughout: a repeated path is a `duplicate` rejection rather than a second
+ * bundle, and every downstream derivation (bundle.ts) keeps the same direction.
+ */
+export declare function loadPlugins(plugins: readonly SdkPluginConfig[] | undefined, opts?: {
+    cwd?: string;
+    brand?: Pick<BrandProfile, "pluginManifestDir">;
+}): LoadPluginsResult;

package/dist/plugins/manifest.d.ts

@@ -0,0 +1,115 @@
+import { type BrandProfile } from "@yanlinglabs/winter-agent-sdk";
+/** Winter's OWN manifest dir, derived rather than spelled. A session's is `brand.pluginManifestDir`. */
+export declare const WINTER_PLUGIN_MANIFEST_DIR: string;
+export declare const CLAUDE_PLUGIN_MANIFEST_DIR = ".claude-plugin";
+export declare const PLUGIN_MANIFEST_FILE = "plugin.json";
+/**
+ * Preference order for a given brand: the brand's own dir first, so a plugin shipping both is read
+ * as native. `.claude-plugin` is never rebranded -- it is the official runtime's own name (WS-01 §5).
+ */
+export declare function pluginManifestDirs(brand?: Pick<BrandProfile, "pluginManifestDir">): readonly string[];
+/** The default profile's pair, for every caller that has not threaded a brand. */
+export declare const PLUGIN_MANIFEST_DIRS: readonly string[];
+/**
+ * Open-keyed for the same reason `Settings` is: a manifest key Winter does not know about is
+ * PRESERVED and inert rather than dropped, so a plugin authored for a newer engine still loads.
+ */
+export interface PluginManifest {
+    name?: string;
+    version?: string;
+    description?: string;
+    author?: unknown;
+    homepage?: string;
+    keywords?: string[];
+    /** Settings-shaped `{ <Event>: [{matcher?, hooks: [...]}] }` -- carried verbatim; parsed by the hook loader. */
+    hooks?: unknown;
+    /** RAW per-name configs; validated by Lane A's `resolveMcpServerSources`, never here. */
+    mcpServers?: Record<string, unknown>;
+    /**
+     * WS-21 fix round 4 (minors, M-3's last bullet): custom workflow source path(s), REPLACING the
+     * default `workflows/` directory rather than adding to it -- confirmed by content search against
+     * the installed claude CLI binary (`opt/homebrew/Caskroom/claude-code@latest`, 2.1.280; the pinned
+     * 2.1.250 was unavailable locally, so this is the closest available build, cited by content, not
+     * by offset): `if(j.workflows){let jn=Array.isArray(j.workflows)?j.workflows:[j.workflows],
+     * qn=await Tb(jn,e,j.name,n,"workflows","Workflow","specified in manifest but",M,B,!1,h);if
+     * (qn.length>0)ve.workflowsPaths=qn}`, and the default directory is populated only through a
+     * SEPARATE `Lt=!j.workflows&&Be` gate a few lines above -- `Lt` is false whenever `j.workflows` is
+     * present at all, regardless of whether any entry resolves. Each entry may name a DIRECTORY
+     * (scanned the same way as the default one) or a single FILE (the SAME `Tb` call site passes
+     * `requireDirectory:!1` for `workflows`, unlike the `!0` it passes for `skills`, which is the
+     * fourth-from-last argument and the one place the two calls differ). `plugins/loader.ts`'s
+     * `resolveManifestComponentOverride` (fix round 5's own generalisation) is where this is resolved
+     * into `PluginBundle.workflowsPaths`.
+     */
+    workflows?: string | string[];
+    /**
+     * WS-21 fix round 5: the same custom-path-override shape as `workflows` above, for the built-in
+     * `agents/` component -- content-search confirmed against the installed claude CLI binary
+     * (2.1.280): `if(pt)ve.agentsPath=$t;if(j.agents){let jn=Array.isArray(j.agents)?j.agents:
+     * [j.agents],qn=await Tb(jn,e,j.name,n,"agents","Agent","specified in manifest but",M,B,!1,h);if
+     * (qn.length>0)ve.agentsPaths=qn}` -- `pt=!j.agents&&Fe` shadows the default directory on the
+     * key's mere presence, the identical `!j.X&&Y` shape `workflows`' own `Lt` gate has. The CONSUMER
+     * side (dump-confirmed separately, a different chunk of the same binary) stat()s each entry and
+     * branches directory-vs-file: `M.agentsPaths.map(async(he)=>{let ve=await stat(he);if(ve.
+     * isDirectory()){...scan the dir...}else if(...){...one file...}})` -- ported as
+     * `scanPluginAgentsOverride`.
+     */
+    agents?: string | string[];
+    /**
+     * WS-21 fix round 5: the same custom-path-override shape as `workflows`/`agents`, for `commands`
+     * -- PLUS an inline `{<name>: {source?: string; content?: string}}` object-map form claude's own
+     * `eqt` also accepts (content-search confirmed against the installed claude CLI binary, 2.1.280),
+     * letting a manifest embed a command's text directly instead of pointing at a file. Winter does
+     * NOT port the inline form this round (`plugins/loader.ts`'s `resolveCommandsManifestOverride` has
+     * the full disclosed-scope note); it is typed here only so a manifest using it is not silently
+     * miscast, and so the shadow-on-presence check still fires for it.
+     */
+    commands?: string | string[] | Record<string, {
+        source?: string;
+        content?: string;
+    }>;
+    /**
+     * WS-21 fix round 5: `skills` is a manifest custom-path override too, but content-search confirmed
+     * against the installed claude CLI binary (2.1.280) shows a DIFFERENT precedence than every other
+     * component here -- ADDITIVE, not shadow-on-presence. The builder's own gate (`_t=Le`, no `!j.
+     * skills` negation, unlike `commands`' `ht=!j.commands&&Me`/`agents`' `pt=!j.agents&&Fe`/
+     * `workflows`' `Lt=!j.workflows&&Be`) sets the default `ve.skillsPath` REGARDLESS of whether
+     * `j.skills` is also present; the CONSUMER (a separate chunk of the same binary) confirms it:
+     * `if(h.skillsPath){...load the default...}if(h.skillsPaths){...ALSO load every override entry...}`
+     * -- both run, never either/or. Consistent with this: `skills` is ABSENT from the
+     * `folder-shadowed-by-manifest` tuple list (`["commands",...],["agents",...],["outputStyles",...],
+     * ["themes",...]` -- no `"skills"` entry), so no shadow warning is possible for it.
+     * `plugins/loader.ts`'s `scanPluginSkillsOverride` is where this is resolved and merged.
+     */
+    skills?: string | string[];
+    /**
+     * WS-21 fix round 5: the same custom-path-override shape as `agents`/`workflows` (shadow-on-
+     * presence, `requireDirectory:false`) for `output-styles` -- content-search confirmed against the
+     * installed claude CLI binary (2.1.280): `gt=j.outputStyles` (note the CAMEL-CASE manifest key,
+     * unlike the kebab-case default DIRECTORY name `output-styles/`), `Rt=!gt&&He` shadows the default
+     * on presence, and `if(gt){...Tb(...,"output-styles","Output style",...,!1,...);if(qn.length>0)
+     * ve.outputStylesPaths=qn}`. Resolved LAZILY (unlike commands/agents/skills, which are eagerly
+     * scanned at load time): `context/output-styles.ts`'s `PluginOutputStyleSource.outputStylesPaths`
+     * is where a `<plugin>:<style>` lookup actually reads it.
+     */
+    outputStyles?: string | string[];
+    [key: string]: unknown;
+}
+export interface ReadPluginManifestResult {
+    manifest?: PluginManifest;
+    /** Absolute path of the manifest that was read. */
+    path?: string;
+    /** Set iff a manifest EXISTED but could not be used. A missing manifest sets neither field. */
+    error?: string;
+}
+/**
+ * Read a plugin root's manifest.
+ *
+ * `{}` (all three fields absent) means NO manifest -- the manifestless case, which WS-11 §4 makes a
+ * first-class shape (the root is then named by its basename). A manifest that exists but is
+ * unparseable or is not a JSON object returns `error` instead: loading it as though it were absent
+ * would silently rename the plugin and drop everything it declared.
+ */
+export declare function readPluginManifest(root: string, brand?: Pick<BrandProfile, "pluginManifestDir">): ReadPluginManifestResult;
+/** A manifest's `author`, reduced to a display string. Accepts the bare-string and `{name}` forms. */
+export declare function manifestAuthor(author: unknown): string | undefined;