@yanlinglabs/winter-agent-runtime 0.0.27

package/dist/skills/store.d.ts

@@ -0,0 +1,163 @@
+import { type BrandProfile, type SettingSource } from "@yanlinglabs/winter-agent-sdk";
+import { type DiscoveredSkill, type SkillScanError, type SkillTier } from "./loader.js";
+import { type StrictPluginOnlyCustomization } from "../settings/loaders/strict-plugin-only.js";
+/**
+ * WS-01 §2.4 / WS-11 §4: the PROJECT DOT-DIRECTORY (`brand.projectDirName`) is the canonical plugin
+ * name for itself. The official branch loads `<project>/<projectDir>` as a local plugin, so ITS
+ * skills are `<projectDir>:<skill>`; native discovery reads the same tree directly as the `project`
+ * tier.
+ *
+ * DISCLOSED JUDGMENT CALL (report): a project skill is therefore given TWO names -- its bare name
+ * (its primary identity, what the listing shows and what `/name` uses) and `<projectDir>:<name>` as
+ * an ALIAS. Both resolve through `get()`/`load()` and both are matched by a permission rule
+ * (permission-rules.ts), which is what WS-11 §4's "permission rules match identically across
+ * branches" requires operationally. The alternative readings each break something: bare-only makes
+ * a qualified rule written against the official branch inert here, and qualified-only makes
+ * `/review` and `Skill("review")` stop working for every project skill.
+ *
+ * P7a (D19): Winter's OWN value, derived rather than spelled. A session's is
+ * `SkillIndexOptions.brand.projectDirName`.
+ */
+export declare const PROJECT_PLUGIN_NAME: string;
+export interface SkillMeta {
+    name: string;
+    description: string;
+    source: SkillTier;
+    path: string;
+    author?: string;
+    plugin?: string;
+    /** Every OTHER name this skill answers to (see PROJECT_PLUGIN_NAME). Never includes `name`. */
+    aliases?: string[];
+}
+/** One plugin's contribution, pre-parsed by plugins/loader.ts -- this file never reads a plugin manifest. */
+export interface PluginSkillContribution {
+    plugin: string;
+    skills: Array<{
+        name: string;
+        description: string;
+        path: string;
+        author?: string;
+    }>;
+}
+export interface SkillIndexOptions {
+    cwd: string;
+    /**
+     * The RESOLVED winter root -- i.e. what `resolveWinterHome(env, brand)` /
+     * `resolveProductionWinterHome` return, which is `<PREFIX>HOME` when set and
+     * `<os home>/<brand.homeDirName>` otherwise.
+     *
+     * NAMED `winterHome`, NOT `home`, DELIBERATELY. Two conventions exist side by side in this
+     * codebase and they are not interchangeable: `ResolveSettingsDetailedOptions.winterHome` is the
+     * resolved root itself, while `LoadAgentDefinitionsOptions.home` is the OS home directory and
+     * appends the dot-dir internally. Only the first can honour `<PREFIX>HOME` -- an override may
+     * point anywhere and need not be named after the brand at all -- and WS-01 §2.5 makes
+     * `<PREFIX>HOME` the user tier's address. A field called `home` here would be handed
+     * `resolveProductionWinterHome(...)` by a caller reading the settings convention and
+     * `ctx.home`/`homedir()` by one reading the agents convention; one of the two silently finds an
+     * empty user tier. The name is the only thing that stops that.
+     *
+     * ALWAYS explicit -- this module never reads `process.env` (a shared-process `bun test` would race).
+     */
+    winterHome: string;
+    /** P7a (D19): the session's brand -- the project dot-dir and its qualified-skill prefix. Omitted = `WINTER_BRAND`. */
+    brand?: Pick<BrandProfile, "projectDirName"> | undefined;
+    /** Omitted = all three tiers; `[]` = filesystem discovery disabled. */
+    settingSources?: SettingSource[] | undefined;
+    plugins?: readonly PluginSkillContribution[] | undefined;
+    /**
+     * The BUILTIN registry seam. Winter ships no bundled skills at P5 -- this is deliberately an empty
+     * default rather than a directory scan, so the tier EXISTS (listing, precedence, the
+     * `disableBundledSkills` gate) without inventing content. Disclosed in the report.
+     */
+    builtinSkills?: readonly DiscoveredSkill[] | undefined;
+    /**
+     * `Settings.disableBundledSkills` (`sdk.d.ts:5657`). Removes the builtin tier and nothing else.
+     *
+     * Like every other settings-derived option on this interface, it arrives from `Settings`' INDEX
+     * SIGNATURE as `unknown` and must be narrowed by the caller -- see
+     * `settings/loaders/strict-plugin-only.ts`'s header for the full list and why.
+     */
+    disableBundledSkills?: boolean | undefined;
+    /**
+     * `Settings.strictPluginOnlyCustomization` (`sdk.d.ts:5988`). When it covers `"skills"`, ONLY
+     * plugin-contributed skills load -- project, user, self and builtin are all excluded. Distinct
+     * from source gating: `settingSources` says which settings FILES load, this says which
+     * customization SOURCES may customize at all.
+     */
+    strictPluginOnlyCustomization?: StrictPluginOnlyCustomization | undefined;
+    bodyBytes?: number | undefined;
+    /**
+     * Fix round 4 (I-E, the router same-view test): a workflow, registered as a SYNTHETIC skill so
+     * `Skill("<name>")` and the slash-command surface both run it -- claude's own `m()` turns every
+     * discovered workflow into exactly this shape (dump-confirmed: `{type:"prompt", kind:"workflow",
+     * ...}`). Unlike every other entry `discover()` finds, a synthetic entry carries its own BODY
+     * directly (`load()` returns it as-is, never reading `path` from disk -- there is no SKILL.md a
+     * workflow script's own identity could point `load()` at). `path` is still required on the
+     * resulting `SkillMeta` (a synthetic, non-filesystem marker -- `workflows/store.ts`'s own
+     * `WorkflowListingEntry.path`, the REAL `.js` script path, doubles as it: informative for a
+     * listing/debug consumer, never read from by `load()` for a synthetic entry).
+     */
+    syntheticSkills?: readonly {
+        name: string;
+        description: string;
+        body: string;
+        source: SkillTier;
+        path: string;
+        plugin?: string;
+    }[];
+}
+/**
+ * The startup index. Immutable once built: a session's skill surface is resolved at start, never
+ * re-scanned mid-turn (the pinned branch reloads on an explicit control request, never on a watcher
+ * -- derived-shapes-p5 item (b); Winter's own "no watchers inside the SDK" rule agrees).
+ */
+export declare class SkillIndex {
+    private readonly entries;
+    private readonly byName;
+    private readonly bodyBytes;
+    private readonly scanErrors;
+    /** Fix round 4 (I-E): a synthetic entry's own body, keyed by its PRIMARY name -- `load()` checks this before ever touching disk. */
+    private readonly syntheticBodies;
+    private constructor();
+    static build(opts: SkillIndexOptions): SkillIndex;
+    /**
+     * Every SKILL.md that could NOT become an entry, with the reason (A-11).
+     *
+     * The listing is built from `list()`; this is the parallel channel that stops a broken or oversized
+     * skill from simply not existing. A host that surfaces `wiring.warnings` should include these --
+     * that wiring is another lane's file in this wave and is named in the report as NEEDS_CONTEXT.
+     */
+    errors(): SkillScanError[];
+    /** Every skill, in precedence order, by PRIMARY name. Aliases are not separate entries. */
+    list(): SkillMeta[];
+    /** Primary names only, in precedence order -- the `system/init.skills` producer's input. */
+    names(): string[];
+    /** Resolve a name OR an alias to its metadata. */
+    get(name: string): SkillMeta | undefined;
+    /** Every name a skill answers to (primary first) -- what a permission rule is matched against. */
+    identities(name: string): string[];
+    /**
+     * Read a skill's body FROM DISK, byte-capped. `null` for an unknown name and for a skill whose
+     * file has since been deleted, moved or made unparseable -- an invocation must degrade to a typed
+     * tool error, never crash the turn.
+     *
+     * Fix round 4 (I-E): a SYNTHETIC entry (a workflow registered as a skill) returns its own
+     * pre-built body directly, keyed by the RESOLVED meta's primary name (so an alias lookup still
+     * finds it) -- never touching disk at all, since there is no SKILL.md a workflow script's identity
+     * could point this at.
+     *
+     * Fix round 7 (a same-day follow-up to round 6): `isSynthetic` lets a caller (`commands/
+     * resolver.ts`'s `resolve()`) tell a synthetic (workflow-backed) body apart from an ordinary,
+     * on-disk one -- round 6 put `$ARGUMENTS_JSON` into the SHARED `substituteArguments`, making it a
+     * recognised token in EVERY skill/command body; this is the seam that lets the fix scope the JSON
+     * substitution to synthetic bodies only, without the resolver having to re-derive "is this a
+     * workflow" from the name or path.
+     */
+    load(name: string): {
+        name: string;
+        body: string;
+        source: SkillTier;
+        path: string;
+        isSynthetic: boolean;
+    } | null;
+}

package/dist/store/continuation-attach.d.ts

@@ -0,0 +1,44 @@
+import type { SdkMessage } from "@yanlinglabs/winter-agent-sdk";
+import { type ContinuationChain, type ProviderStateRecord } from "./provider-state.js";
+/** The half of `SessionPersistence` this needs. Narrowed so a caller can hand it a two-method double. */
+export interface ContinuationChainSource {
+    loadProviderState?(): Promise<ProviderStateRecord[]>;
+    loadProviderIdentity?(): Promise<{
+        providerId: string;
+        modelKey: string;
+    } | undefined>;
+}
+/** The shape this mutates. Deliberately structural rather than importing `ProviderMessage` from `engine.ts` -- that direction is the circular one `store/` must not take. */
+export interface AttachableMessage {
+    role: "user" | "assistant" | "tool" | "system";
+    uuid?: string;
+    origin?: unknown;
+    nativeState?: unknown;
+}
+export interface AttachContinuationChainOptions {
+    messages: AttachableMessage[];
+    store: ContinuationChainSource;
+    sessionId: string;
+    /** Emits one Winter-only `system/continuity_warning`. Called at most once. */
+    warn: (message: SdkMessage) => void;
+    /** Injected so a fixture's warning uuid is deterministic. */
+    newUuid: () => string;
+    /**
+     * P6 fix wave (T10 r1 Minor): the persisted identity, ALREADY LOADED by the caller. The engine reads
+     * it once for the resume-time switch comparison; without this the zero-records branch below re-read
+     * it -- one extra summary I/O per resumed run. Absent -> `store.loadProviderIdentity` as before.
+     */
+    identity?: () => Promise<{
+        providerId: string;
+        modelKey: string;
+    } | undefined>;
+}
+/**
+ * Folds the sidecar chain back onto a resumed history, and REPORTS a gap.
+ *
+ * An assistant message with no `origin` record degrades to summary-level and the session says so.
+ * That is R6-7's own rule, and the reason it cannot be silent is that the degradation is observable
+ * to the model: it will not get its exact native replay, so a user who sees a worse continuation than
+ * they expected deserves to know why.
+ */
+export declare function attachContinuationChain(opts: AttachContinuationChainOptions): Promise<ContinuationChain>;