@yanlinglabs/winter-agent-runtime 0.0.27

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yanlingLabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,41 @@
+NOTICE
+======
+
+Third-party attributions for the Winter agent SDK.
+
+This file records material that Winter DERIVED FROM third-party artifacts. Winter copies no source
+code from any of them; what it takes is protocol facts — endpoint URLs, form-field names, client
+identifiers and scope strings — which it needs in order to speak to a vendor's service at all. Each
+entry names the exact commit the values were read at, so the derivation is re-checkable.
+
+
+-------------------------------------------------------------------------------
+xai-org/grok-build
+-------------------------------------------------------------------------------
+
+    Repository:  https://github.com/xai-org/grok-build
+    Commit:      72a61251fcffb464bcc687aeb5a998e5a98ec0c9
+    License:     Apache License, Version 2.0
+                 https://www.apache.org/licenses/LICENSE-2.0
+    Copyright:   Copyright 2023-2026 SpaceXAI
+
+Winter's `xai-oauth` provider derives the following constants and request shapes from this
+repository's authentication module, in order to perform its own OAuth 2.0 device authorization
+grant (RFC 8628) against xAI's public, secret-less OAuth client:
+
+  - the public OAuth client identifier
+  - the OAuth issuer, device-authorization endpoint and token endpoint
+  - the requested scope set
+  - the name of the form field the flow carries a client identity in
+  - the shape (field names) of the device-authorization and token requests
+
+No source code from this repository is copied into Winter, and no part of Winter is a derivative
+work of it. The derivation is recorded, with per-value line citations, in:
+
+    packages/conformance/compat/xai/grok-build/derived-shapes-p6b-xai.md
+
+Winter identifies ITSELF in that flow. It sends its own `User-Agent` (`winter-agent-sdk/<version>`)
+and its own name in the flow's identity field, and it does not send xAI's product-identity or
+telemetry headers. Winter is not affiliated with or endorsed by SpaceXAI, and "Grok" and "Grok Build"
+are the marks of their owner; they appear here and in the capture solely to identify the artifact
+these values were derived from.

package/README.md

@@ -0,0 +1,64 @@
+# `@yanlinglabs/winter-agent-runtime`
+
+Winter's agent engine: the turn loop, the built-in tools, the session store and the provider wiring
+that the compiled `winter` binary runs. Most hosts never install this package — they install
+`@yanlinglabs/winter-agent-sdk`, whose `query()` spawns that binary.
+
+This package is for a host that wants to run sessions **in its own process** instead. It is Bun-only.
+
+## Install
+
+This package is published to **two registries**, and which one you want depends on who you are.
+
+### From public npm (anyone)
+
+```sh
+npm install @yanlinglabs/winter-agent-runtime
+```
+
+Nothing else is needed: the `@yanlinglabs` scope is public on npm.
+
+### From GitHub Packages (the `yanlingLabs` org)
+
+GitHub Packages needs the scope pointed at it and an authenticated read, even for a public package.
+In your project's `.npmrc`:
+
+```
+@yanlinglabs:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
+```
+
+…with `GITHUB_TOKEN` in the environment — a personal access token carrying `read:packages`, never a
+literal in the file. Then `npm install @yanlinglabs/winter-agent-runtime` as usual.
+
+**The published packages contain COMPILED OUTPUT ONLY.** Each tarball ships `dist/` — the bundled
+JavaScript a consumer imports and the `.d.ts` declarations their type-checker reads — plus
+`README.md`, `NOTICE` and `LICENSE`. The TypeScript sources live at
+<https://github.com/yanlingLabs/winter-agent-sdk>, which is where to read them, file an issue, or send
+a patch.
+
+This package, `@yanlinglabs/winter-agent-sdk` and its platform binary package are released together
+at one version, and each pins the others exactly.
+
+## Embedding a session
+
+The runtime keeps per-process state (its tool registry, MCP executors, background-task table), so
+each session needs its own JavaScript realm: run one session per Bun `Worker`.
+
+- `@yanlinglabs/winter-agent-runtime/embedded-host` — `spawnEmbeddedWorker(...)` constructs the Worker
+  and returns a `SpawnedRuntimeProcess`. Hand it to `query()` through `Options.spawnClaudeCodeProcess`.
+  The frames on the wire are exactly the ones the spawned binary writes. This module does not load
+  the engine, so it is safe to import on a host's main thread.
+- `@yanlinglabs/winter-agent-runtime/embedded-worker` — the Worker entry. A compiled
+  (`bun build --compile`) host passes its own one-line worker file as an extra entrypoint and
+  constructs the Worker from that file's plain relative path.
+- `@yanlinglabs/winter-agent-runtime/embedded` — `runEmbeddedSession(...)`, one session with every
+  process global (argv, env, stdio, exit) as a parameter.
+- `@yanlinglabs/winter-agent-runtime/workflow-worker` — the Workflow tool's sandboxed worker entry,
+  for a host that routes its own binary's argv to it.
+- `@yanlinglabs/winter-agent-runtime/version` — `RUNTIME_VERSION`, with no other imports. A host
+  should check that it equals the wrapper's `SDK_VERSION` before it runs a session.
+
+## License
+
+MIT — see [`LICENSE`](./LICENSE), which ships in the published tarball.

package/dist/checkpoint/file-history.d.ts

@@ -0,0 +1,81 @@
+/** The directory name under `~/.winter`. One constant so a fixture and the sink cannot disagree. */
+export declare const CHECKPOINT_DIRNAME = "file-history";
+/** The private per-session record of intercepted mutations. */
+export declare const CHECKPOINT_INDEX_FILENAME = "index.jsonl";
+export type CheckpointRecordKind = "snapshot" | "delta";
+export interface CheckpointRecord {
+    kind: CheckpointRecordKind;
+    /** The envelope this mutation belongs to -- the unit `rewind` restores to. */
+    userMessageUuid: string;
+    /** Absolute, resolved. */
+    path: string;
+    pathHash: string;
+    /** Which mutating tool announced it. Recorded for auditability; the rewind does not branch on it. */
+    tool: string;
+    at: string;
+    /**
+     * The blob version for a snapshot (`<path-hash>@v<version>`); for a delta, the snapshot version it
+     * follows. Counts SNAPSHOTS only, so the blob numbering is dense and `@v2` really is the second
+     * backup of that file rather than the second time it was touched.
+     */
+    version: number;
+    /** The file did not exist at checkpoint time -- there are no bytes, and a rewind DELETES it. */
+    absent?: boolean;
+    /**
+     * `realpath(dirname(path))` at checkpoint time. Item (e)'s rule: a path whose parent no longer
+     * resolves where it did is REFUSED rather than restored -- otherwise a rewind follows a directory
+     * that has since become a link and writes the pre-image into somebody else's tree.
+     *
+     * KEPT ALONGSIDE the anchor pair below rather than replaced by it. It costs one string, it is
+     * checked independently, and removing a guard is never the safe direction -- it also keeps records
+     * written by an earlier build fully protected.
+     *
+     * **It is absent exactly when the parent did not exist at checkpoint time**, which is precisely the
+     * `absent: true` case whose rewind arm DELETES the file. That is why it cannot be the only
+     * path-identity guard: see `anchorPath`.
+     */
+    parentRealPath?: string;
+    /**
+     * The nearest ancestor directory that EXISTED at checkpoint time, as written (not realpath'd), plus
+     * its real path at that moment. Recorded for EVERY record, including one whose own parent did not
+     * exist yet -- a `Write` to a path the tool is about to `mkdir -p`.
+     *
+     * This is the fix for a demonstrated hole: with `parentRealPath` absent on exactly those records,
+     * the delete arm ran with NO path-identity check at all, so replacing the not-yet-existing
+     * directory with a symlink let a rewind `rmSync` a file the session had never touched. At rewind
+     * the anchor must still resolve to `anchorRealPath` AND no component between it and the target may
+     * have become a symlink.
+     */
+    anchorPath?: string;
+    anchorRealPath?: string;
+}
+export declare function checkpointPathHash(absolutePath: string): string;
+export declare function sessionCheckpointDir(home: string, sessionUuid: string): string;
+export declare function blobName(pathHash: string, version: number): string;
+/** `realpath` of the parent, or undefined when it cannot be resolved (the directory is gone). */
+export declare function parentRealPathOf(absolutePath: string): string | undefined;
+/**
+ * The nearest ancestor DIRECTORY of `absolutePath` that exists right now, with its real path.
+ * Walks upward until something resolves, so it answers even for a path several not-yet-created
+ * directories deep -- which is the whole point: a checkpoint taken before `mkdir -p` still gets a
+ * real anchor to verify against later.
+ *
+ * Returns undefined only if nothing up to the filesystem root resolves, which in practice means the
+ * volume itself is gone; the rewind then refuses rather than guessing.
+ */
+export declare function nearestExistingAncestor(absolutePath: string): {
+    anchorPath: string;
+    anchorRealPath: string;
+} | undefined;
+/**
+ * Reads the session's records, oldest first. A missing directory or file is an EMPTY history, never
+ * an error: `rewind` on a session that has mutated nothing must answer "nothing to rewind to", and
+ * a `dryRun` must not bring the directory into existence just by asking.
+ *
+ * A malformed line is skipped rather than fatal -- a truncated final line (a process killed
+ * mid-append) must not make every earlier checkpoint unreadable.
+ */
+export declare function readCheckpointIndex(home: string, sessionUuid: string): CheckpointRecord[];
+export declare function appendCheckpointRecord(home: string, sessionUuid: string, record: CheckpointRecord): void;
+/** The pre-image bytes, or undefined when the file does not exist / is not a regular file. */
+export declare function readPreImage(absolutePath: string): Buffer | undefined;

package/dist/checkpoint/rewind.d.ts

@@ -0,0 +1,55 @@
+import type { RewindFilesResult } from "@yanlinglabs/winter-agent-sdk";
+import { type CheckpointRecord } from "./file-history.js";
+/**
+ * Line counts, Winter-defined and DISCLOSED: the pin declares `insertions`/`deletions` as numbers and
+ * defines no algorithm for them. This is a MULTISET (bag) difference -- for each distinct line, the
+ * surplus in one side over the other -- which is O(n+m), deterministic, and exact for the pure
+ * insert/delete edits a rewind actually undoes. A minimal-edit-script (LCS) count would be O(n*m)
+ * over arbitrary files, and a rewind must not become the slowest thing in a session.
+ *
+ * `insertions` = lines the rewind ADDS (present in the restored content, missing from the current);
+ * `deletions` = lines it REMOVES. Reported from the FILE's point of view, matching the direction a
+ * host renders as "+/-".
+ */
+export declare function countLineDelta(current: string[], restored: string[]): {
+    insertions: number;
+    deletions: number;
+};
+/** A trailing newline terminates the last line rather than starting an empty one. */
+export declare function splitLines(content: Buffer | undefined): string[];
+/**
+ * PATH-IDENTITY refusals: the recorded path no longer names the file the checkpoint was about, so a
+ * restore would write into -- or DELETE -- somebody else's tree.
+ *
+ * Three independent guards, all cheap, none removable:
+ *
+ *  1. the nearest ancestor that existed at checkpoint time must still resolve to the same real
+ *     directory (`anchorPath`/`anchorRealPath`);
+ *  2. no component between that ancestor and the target may have become a symlink since;
+ *  3. the legacy immediate-parent check, kept because removing a guard is never the safe direction
+ *     and because it still protects records written by an earlier build.
+ *
+ * Guards 1 and 2 exist because guard 3 alone was INERT ON EXACTLY THE RECORDS THE DELETE ARM ACTS
+ * ON: `parentRealPath` is absent precisely when the parent did not exist at checkpoint time, which
+ * is the `absent: true` case, which is the case `rmSync` services. Replacing the not-yet-created
+ * directory with a symlink then let a rewind delete a never-checkpointed file, silently.
+ *
+ * These are evaluated on a `dryRun` TOO -- see `rewindToCheckpoint` for why that is not the
+ * "previews do not reflect refusals" clause.
+ */
+export declare function describeRefusal(record: Pick<CheckpointRecord, "path" | "anchorPath" | "anchorRealPath" | "parentRealPath">): string | undefined;
+export interface RewindOptions {
+    home: string;
+    sessionUuid: string;
+    userMessageUuid: string;
+    dryRun: boolean;
+    /**
+     * T8 rider 25: the session's own writable roots (its `cwd` plus any `additionalDirectories`). A
+     * record naming a path outside every one of them is REFUSED -- see `isInsideSessionRoots`.
+     *
+     * REQUIRED, not optional-defaulting-to-unfenced: an omitted fence is exactly the state this rider
+     * closes, and a caller that genuinely wants no fence has to say so by passing `["/"]`.
+     */
+    roots: readonly string[];
+}
+export declare function rewindToCheckpoint(opts: RewindOptions): RewindFilesResult;

package/dist/checkpoint/seam.d.ts

@@ -0,0 +1,47 @@
+import type { RewindFilesResult } from "@yanlinglabs/winter-agent-sdk";
+/** The three mutating tools checkpointing intercepts, as one exported set so the engine's check and a lane's own fixtures cannot drift. */
+export declare const CHECKPOINTED_TOOLS: readonly ["Write", "Edit", "NotebookEdit"];
+export type CheckpointedTool = (typeof CHECKPOINTED_TOOLS)[number];
+export declare function isCheckpointedTool(name: string): name is CheckpointedTool;
+export interface CheckpointMutation {
+    path: string;
+    tool: CheckpointedTool;
+    /** The engine-minted id of the user envelope this mutation belongs to -- the unit `rewind` restores to. */
+    userMessageUuid: string;
+    sessionUuid: string;
+}
+export interface FileCheckpointSink {
+    /**
+     * Called BEFORE the mutation runs, once per candidate write path. A sink that throws does NOT stop
+     * the write: the engine treats a checkpoint failure the way it treats a store failure -- auxiliary,
+     * reported, never turn-fatal. That is a deliberate choice in the safe direction for the USER'S WORK
+     * (the edit they asked for still happens) and the unsafe one for undo, so a sink that cannot back
+     * up must say so loudly rather than failing silently.
+     */
+    beforeMutation(req: CheckpointMutation): Promise<void>;
+    /**
+     * Restores every tracked file to its state at `userMessageUuid`. `dryRun` previews without
+     * touching the filesystem -- and, per item (e), without populating `skippedLinks`.
+     *
+     * Returns `canRewind: false` with an `error` for an unknown/untracked id rather than throwing: the
+     * control request that reaches this is a host action, and "there is nothing to rewind to" is an
+     * answer, not a failure.
+     */
+    rewind(userMessageUuid: string, opts?: {
+        dryRun?: boolean;
+    }): Promise<RewindFilesResult>;
+}
+/**
+ * The spine's test double: an in-memory sink recording every intercepted mutation and answering
+ * `rewind` from a canned table. It touches no filesystem at all -- Lane K's real sink is what proves
+ * backup/restore.
+ */
+export declare function fakeFileCheckpointSink(opts?: {
+    mutations?: CheckpointMutation[];
+    results?: Record<string, RewindFilesResult>;
+    rewindCalls?: Array<{
+        userMessageUuid: string;
+        dryRun: boolean;
+    }>;
+    failBeforeMutation?: string;
+}): FileCheckpointSink;

package/dist/checkpoint/sink.d.ts

@@ -0,0 +1,66 @@
+import type { FileCheckpointSink } from "./seam.js";
+import { type CheckpointRecord } from "./file-history.js";
+export { CHECKPOINT_DIRNAME, CHECKPOINT_INDEX_FILENAME } from "./file-history.js";
+export interface FileCheckpointSinkOptions {
+    /**
+     * The session this sink rewinds. REQUIRED, because `rewind(userMessageUuid)` carries no session of
+     * its own: checkpoints belong to a session (WS-11 §9's scope row), and a sink that guessed would
+     * let one session undo another's work.
+     */
+    sessionUuid: string;
+    /**
+     * The resolved product root (`<PREFIX>HOME` || `~/<homeDirName>`), the directory this sink writes
+     * its backups and its index under. REQUIRED.
+     *
+     * P7a fix wave (item 5, whole-branch review M-5): it used to default to `resolveWinterHome(opts.env)`
+     * -- WITH NO BRAND -- which reads `WINTER_HOME` and `~/.winter`. Unreachable today (the sole
+     * production caller, `production-wiring.ts`, passes the session's own resolved root), but it is the
+     * same shape as I-1 one call site away from being live: a reuser's checkpoints would have been
+     * written into, and rewound from, WINTER's home. There is no brand-neutral default to fall back
+     * to, so the parameter is required rather than brand-threaded -- a caller that has a session at
+     * all has already resolved its root, and one that has not must not be given Winter's.
+     *
+     * Every test passes a mkdtemp root.
+     */
+    home: string;
+    /**
+     * Resolves a RELATIVE candidate write path. `extractCandidateWritePaths` yields the path the tool
+     * call carried, which is usually but not always absolute -- and the backup identity is the hash of
+     * the ABSOLUTE path, so resolving late would file two spellings of one file as two histories.
+     *
+     * WS-23: REQUIRED -- it used to default to `process.cwd()`, which inside an embedded session's
+     * Worker is the host daemon's cwd, so a relative write path would have been filed under the wrong tree.
+     */
+    cwd: string;
+    /**
+     * T8 rider 25 (SECURITY): extra roots the session was configured to write outside `cwd`
+     * (`RuntimeConfig.additionalDirectories`). `rewind` refuses a record naming a path outside `cwd`
+     * and these, so a tampered `index.jsonl` cannot become an arbitrary write or delete -- but a file
+     * the session GENUINELY edited in a granted directory must still restore, which is what this
+     * field carries. Omitted => `cwd` is the whole fence.
+     */
+    additionalDirectories?: readonly string[];
+    /**
+     * Phase 5 Task 8 (riders 9/16): the session's durable transcript sink, so every checkpoint record
+     * is ALSO visible to a transcript reader (`store/dialect.ts`'s `file-history-snapshot` /
+     * `file-history-delta`). Lane K's concern 1 named exactly this cost of the private sidecar.
+     *
+     * A MIRROR, deliberately, and the sidecar remains this sink's own read authority -- see that
+     * module's own header for the two blockers that keep the retirement half of rider 16 open. The
+     * mirror is best-effort: a store failure NEVER fails the mutation it accompanies, matching
+     * `recordHookAudit`/`recordPermissionUpdate`'s established auxiliary-sink policy. A backup that
+     * exists with no transcript line still restores; a transcript line with no backup would be the
+     * dangerous direction, which is why the sidecar write stays first.
+     */
+    persistence?: {
+        recordFileHistory?(record: CheckpointRecord): void | Promise<void>;
+    };
+    /**
+     * P7a fix wave (item 5, M-5): RETAINED but now inert here -- its only reader was the brand-less
+     * `resolveWinterHome(opts.env)` default that `home` replaced. Kept on the options type because
+     * callers pass it and removing it would be a breaking change for no gain; a future reader of an
+     * env-derived value has a place to look.
+     */
+    env?: Record<string, string | undefined>;
+}
+export declare function createFileCheckpointSink(opts: FileCheckpointSinkOptions): FileCheckpointSink;

package/dist/commands/builtins-listing.d.ts

@@ -0,0 +1,40 @@
+import type { FilesystemCommandResolver, SlashCommandInfo } from "./resolver.js";
+/**
+ * The engine's own commands. DELIBERATELY ONE ENTRY: R5-14 ships `/compact [instructions]` and marks
+ * every other built-in capture-pending, and `CommandResolution`'s `builtin` arm is a single literal
+ * for the same reason. Adding one here without adding the engine branch would advertise a command
+ * that resolves to nothing.
+ */
+export declare const BUILTIN_SLASH_COMMANDS: readonly SlashCommandInfo[];
+/**
+ * The full listing: built-ins, then whatever the resolver enumerates (skills, then command files
+ * project > user > plugin), first occurrence winning.
+ *
+ * THE INVARIANT, STATED EXACTLY: **for a given `cwd`**, every name listed here resolves at that same
+ * `cwd`, and to the producer this listing names. Two qualifications, both load-bearing:
+ *
+ *  - **The `cwd` is part of the statement** (fix round 2, Minor B). Command files are discovered by a
+ *    parent-walk from the cwd, so the enumeration genuinely differs between cwds, and
+ *    `FilesystemCommandResolver.list()` defaults to the resolver's CONSTRUCTION cwd while
+ *    `resolve()` always uses the live one it is handed. A caller that lists at one cwd and resolves
+ *    at another is comparing two different namespaces, and the invariant says nothing about that
+ *    pair. Pass `cwd` here whenever the session's cwd may have moved since construction.
+ *  - **Aliases resolve but are not listed** (fix round 2, Medium A). `/.winter:review` resolves to
+ *    the same skill `/review` does; only `review` is advertised. So the invariant is one-directional:
+ *    everything listed resolves, but not everything that resolves is listed.
+ *
+ * WHAT ENFORCES IT: `FilesystemCommandResolver.enumerate()` is the single ordered map both `list()`
+ * and `resolve()` read. It used to be a claim resting on two loops happening to agree, and they did
+ * not -- `list()` walked command files first while `resolve()` walked skills first, so a shadowed
+ * name was listed with the LOSING producer's description and source, and an `off` skill put a name
+ * into `system/init.slash_commands` that `resolve()` answered `none` to.
+ */
+export declare function buildSlashCommandListing(resolver?: FilesystemCommandResolver, cwd?: string): SlashCommandInfo[];
+/**
+ * `system/init.slash_commands` (`4874`): names only, in listing order.
+ *
+ * PASS `cwd` when the session's working directory may have moved since the resolver was built -- see
+ * the invariant above. Omitting it lists the construction cwd's namespace, which is correct at
+ * startup (when the init frame is emitted) and stale afterwards.
+ */
+export declare function slashCommandNames(resolver?: FilesystemCommandResolver, cwd?: string): string[];

package/dist/commands/resolver.d.ts

@@ -0,0 +1,103 @@
+import type { BrandProfile, SettingSource } from "@yanlinglabs/winter-agent-sdk";
+import { type SkillOverrides } from "../skills/listing.js";
+import type { SkillIndex } from "../skills/store.js";
+import { type CommandResolution, type CommandResolver } from "./seam.js";
+/**
+ * Where a `/name` came from. `"builtin"` is the ENGINE's own (commands/seam.ts), never this
+ * resolver's; `"skill"` covers every skill tier, since the skill index has already ranked those.
+ */
+export type SlashCommandOrigin = "builtin" | "project" | "user" | "plugin" | "skill";
+export interface SlashCommandInfo {
+    name: string;
+    description?: string;
+    /** `SlashCommand.argumentHint` (`sdk.d.ts:7932-7949`). */
+    argumentHint?: string;
+    source: SlashCommandOrigin;
+}
+/** One plugin's commands, pre-resolved by plugins/loader.ts. `name` is the BARE name; qualification happens here. */
+export interface PluginCommandContribution {
+    plugin: string;
+    commands: Array<{
+        name: string;
+        path: string;
+        description?: string;
+        argumentHint?: string;
+    }>;
+}
+export interface FilesystemCommandResolverOptions {
+    cwd: string;
+    /** The RESOLVED winter root (`<PREFIX>HOME` when set) -- see `SkillIndexOptions.winterHome` for why this is not called `home`. */
+    winterHome: string;
+    /** P7a (D19): the session's brand -- the project dot-dir the project tier walks. Omitted = `WINTER_BRAND`. */
+    brand?: Pick<BrandProfile, "projectDirName"> | undefined;
+    settingSources?: SettingSource[] | undefined;
+    /** The session's skill index. Skills create `/name` too (WS-11 §2.4) and WIN an overlap. */
+    skills?: SkillIndex | undefined;
+    plugins?: readonly PluginCommandContribution[] | undefined;
+    skillOverrides?: SkillOverrides | undefined;
+}
+/**
+ * `zE`, ported. `namedArgs` is `o` (see this section's header -- always `[]` from every call site in
+ * this codebase today; no Winter frontmatter parser declares one yet).
+ */
+export declare function substituteArguments(body: string, args: string, namedArgs?: readonly string[]): string;
+/**
+ * The workflow-invoke-line substitution ONLY (fix round 7). `workflows/store.ts`'s
+ * `buildWorkflowSkillPrompt` writes a static body whose invoke line embeds the raw args value INSIDE
+ * its own hand-written quotes (`args: $ARGUMENTS_JSON`), and that value needs `"`/`\` escaping the
+ * way claude's own `S(e)` does it -- dump-confirmed at `createWorkflowCommand`'s `getPromptForCommand`,
+ * `a=e?\`{ name: ${i}, args: ${S(e)} }\`:...\`, and controller-confirmed `S` is `JSON.stringify`
+ * (chunk export at dump ~269598). This function is DELIBERATELY SEPARATE from `substituteArguments`
+ * (never merged into it again): only a synthetic, workflow-backed skill body should ever have
+ * `$ARGUMENTS_JSON` recognised as a token at all; every other command/skill body must see claude's
+ * plain single-token behaviour, `$ARGUMENTS_JSON` included -- since claude itself would leave that
+ * text's `_JSON` suffix untouched.
+ *
+ * A single left-to-right scan, not two `.split().join()` passes: `JSON.stringify(args)` can itself
+ * contain the literal substring `$ARGUMENTS` (e.g. `args = "please pass $ARGUMENTS through"` stringifies
+ * to `"please pass $ARGUMENTS through"`), and a later, separate `$ARGUMENTS` pass over that already-
+ * substituted text would incorrectly re-substitute what the JSON pass just inserted. Scanning once,
+ * left to right, and advancing past whatever was just written never re-visits inserted text.
+ */
+export declare function substituteWorkflowArguments(body: string, args: string): string;
+export declare class FilesystemCommandResolver implements CommandResolver {
+    private readonly opts;
+    /**
+     * The enumeration, memoized per `cwd`. `resolve()` receives a cwd (the spine's own signature) and a
+     * session's cwd genuinely moves -- EnterWorktree relocates the session root -- so a set fixed at
+     * construction would go stale for COMMAND FILES. SKILLS deliberately do NOT follow the cwd: they
+     * come from the index built once at startup, which is the same set the model sees in its listing
+     * and through the Skill tool. `/review` and `Skill("review")` resolving to different files would be
+     * the split brain the overlap rule exists to prevent.
+     */
+    private readonly byCwd;
+    private constructor();
+    static build(opts: FilesystemCommandResolverOptions): FilesystemCommandResolver;
+    private scanCommandFiles;
+    /**
+     * THE single ordered enumeration. Insertion order IS precedence: skills first (the overlap rule),
+     * then command files (project nearest-first > user > plugin), first occurrence of a name winning.
+     *
+     * WHY ONE FUNCTION AND NOT TWO LOOPS. `list()` and `resolve()` used to walk opposite orders. For a
+     * name held by both a skill and a command file, `resolve()` returned the skill's body while the
+     * listing reported the command FILE's description, argument hint and source -- and an `off` skill
+     * put a name into `system/init.slash_commands` that `resolve()` answered `none` to, advertising a
+     * command nothing could run. Two orders over one namespace cannot be kept in agreement by care;
+     * they have to be one enumeration.
+     */
+    private enumerate;
+    /**
+     * Every `/name` this resolver ADVERTISES, in enumeration order. Feeds `system/init.slash_commands`.
+     *
+     * PER CWD (fix round 2, Minor B): command files are discovered by a parent-walk from the cwd, so
+     * the answer differs between cwds and `cwd` defaults to the CONSTRUCTION cwd, not the live one.
+     * A caller must feed the SAME cwd to `list()` and `resolve()` for the "everything listed resolves"
+     * invariant to hold -- `slashCommandNames(resolver, cwd)` exists for exactly that.
+     *
+     * ALIASES ARE NOT LISTED (Medium A): `/.winter:review` resolves, but `slash_commands` carries
+     * `review` alone. Advertising both would double every project skill in the init frame and imply two
+     * commands where there is one.
+     */
+    list(cwd?: string): SlashCommandInfo[];
+    resolve(prompt: string, cwd: string): Promise<CommandResolution>;
+}

package/dist/commands/seam.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `{ kind: "builtin" }` -- an engine-owned command. The union is deliberately a SINGLE literal today
+ * (`"compact"`): R5-14 ships `/compact [instructions]` now and marks every other built-in
+ * capture-pending, so a wider union would be inventing names the pinned surface has not been
+ * observed to have. Adding one later is a one-line widening plus an engine branch; a lane never
+ * produces this arm.
+ *
+ * `{ kind: "expand" }` -- `text` is the FULLY EXPANDED prompt (body with `$ARGUMENTS` already
+ * substituted); the engine substitutes nothing itself. `source` is a human-readable provenance
+ * string for diagnostics (e.g. a file path or `plugin:<name>`), never parsed.
+ *
+ * `{ kind: "none" }` -- not a command; the prompt is used verbatim.
+ */
+export type CommandResolution = {
+    kind: "builtin";
+    name: "compact";
+    args: string;
+} | {
+    kind: "expand";
+    text: string;
+    source: string;
+} | {
+    kind: "none";
+};
+export interface CommandResolver {
+    resolve(prompt: string, cwd: string): Promise<CommandResolution>;
+}
+/**
+ * The one built-in, recognised by the engine before any resolver is consulted.
+ *
+ * Returns `undefined` for anything that is not a built-in -- including a bare `/` and any other
+ * `/name`, both of which fall through to the resolver.
+ *
+ * Grammar, deliberately narrow: `/compact` optionally followed by whitespace and free-form
+ * instructions, which are passed through verbatim (trimmed) as `custom_instructions`. `/compaction`
+ * is NOT a match -- the name must be the whole first token.
+ */
+export declare function resolveBuiltinCommand(prompt: string): Extract<CommandResolution, {
+    kind: "builtin";
+}> | undefined;
+/** True for anything the engine should offer to a resolver at all -- see this file's header. */
+export declare function looksLikeCommand(prompt: string): boolean;
+/**
+ * The spine's test double: a resolver over a literal map of `name -> body`. `$ARGUMENTS` is
+ * substituted exactly as R5-14 requires so an engine test proves the engine passes the EXPANDED text
+ * on, and a lane has a producer to develop against.
+ */
+export declare function fakeCommandResolver(commands: Record<string, string>, opts?: {
+    calls?: Array<{
+        prompt: string;
+        cwd: string;
+    }>;
+}): CommandResolver;

package/dist/compaction/controller.d.ts

@@ -0,0 +1,23 @@
+import { DEFAULT_COMPACTION_THRESHOLD } from "@yanlinglabs/winter-agent-sdk";
+import type { CompactionController } from "./seam.js";
+export { DEFAULT_COMPACTION_THRESHOLD };
+export interface CompactionControllerOptions {
+    /**
+     * R5-4's threshold, a DISCLOSED Winter session option (`RuntimeConfig.compactionThreshold`,
+     * default 0.92 -- the constant is the SDK's, declared once in options.ts). A value outside
+     * `(0, 1]` is ignored and the default stands, mirroring `createContextAccountant`'s own treatment
+     * of a nonsense limit: a threshold of 0 would compact before every single provider call and a
+     * threshold above 1 could never fire, and neither is a state a session should be able to reach by
+     * typo.
+     */
+    compactionThreshold?: number;
+    /** How many user/assistant pairs survive a boundary. Default 4 (DEFAULT_RETAINED_PAIRS). */
+    retainedPairs?: number;
+    /** Overrides Winter's authored summary instruction. For fixtures and for a host with its own house style. */
+    instruction?: string;
+    /** Bounds the per-`tool_use` input rendering in the summarizer's view of the transcript. */
+    toolInputPreviewChars?: number;
+}
+export declare class NothingToCompactError extends Error {
+}
+export declare function createCompactionController(opts?: CompactionControllerOptions): CompactionController;

package/dist/compaction/retention.d.ts

@@ -0,0 +1,35 @@
+import type { ProviderMessage } from "../engine.js";
+/** R5-4's own default: the last four user/assistant pairs. An option on the controller. */
+export declare const DEFAULT_RETAINED_PAIRS = 4;
+export interface RetentionPlan {
+    /**
+     * False when the window covers the whole history -- there is no cut that both keeps the requested
+     * pairs and folds anything. `retained` then holds the input unchanged and `summarized` is empty;
+     * the CONTROLLER turns this into a thrown error, because a `CompactionResult` whose `retained` is
+     * the whole input would make the engine's history LONGER (summary + everything) on every round.
+     */
+    foldable: boolean;
+    /** The messages that survive the boundary, in order. */
+    retained: ProviderMessage[];
+    /** The messages the summary replaces -- what the summarizer is asked to condense. */
+    summarized: ProviderMessage[];
+}
+export interface RetentionOptions {
+    /** How many pairs (turns) to keep. Defaults to DEFAULT_RETAINED_PAIRS. */
+    pairs?: number;
+}
+export declare function selectRetention(messages: readonly ProviderMessage[], opts?: RetentionOptions): RetentionPlan;
+/**
+ * WS-09 §8.5: the tools the compacted context still carries EVIDENCE of. `registry.onCompaction`
+ * resets the session's deferred loaded set to `evidenced ∩ still-registered`, so a tool whose call
+ * the summary swallowed goes back to searchable-not-loaded and must be rediscovered.
+ *
+ * DISCLOSED READING of the brief's "deferred tools referenced in retained messages": this returns
+ * EVERY referenced name, not a `descriptor.deferred`-filtered subset. The filtered set would be
+ * behaviourally identical at best -- `LoadedToolSet` only ever holds names Tool Search actually
+ * loaded, and `onCompaction` intersects rather than unions -- and strictly worse at worst: a
+ * descriptor whose `deferred` is a `PermissionMode[]` reads as not-deferred outside those modes, so
+ * filtering here would silently unload a tool the model is still visibly using. Over-reporting
+ * cannot add anything to the loaded set; under-reporting drops something from it.
+ */
+export declare function evidencedToolNames(retained: readonly ProviderMessage[]): string[];