@yanlinglabs/winter-agent-runtime 0.0.27

package/dist/compaction/seam.d.ts

@@ -0,0 +1,115 @@
+import type { ContextAccountant, Provider, ProviderMessage, ProviderRequest } from "../engine.js";
+export interface CompactionInput {
+    messages: ProviderMessage[];
+    trigger: "auto" | "manual";
+    /** `/compact <instructions>` (manual) or a PreCompact hook's forwarded context; `null` when neither. */
+    customInstructions: string | null;
+    accountant: ContextAccountant;
+    /** The SESSION's own provider -- R5-4: the summarizer runs on it, never on a second, separately-configured model. */
+    provider: Provider;
+    /**
+     * WS-23: the session's OWN outbound request for the history as it stands -- the exact system
+     * blocks, tools, model and reasoning settings the main loop last sent, and the outbound message list
+     * (index-0 context and effort markers included). A controller that appends its instruction to this,
+     * rather than building a fresh `{messages, system}` request, reads the whole conversation from the
+     * prompt cache the main loop already wrote -- the way a byte-exact fork does -- instead of paying for
+     * the largest request of the session uncached. ABSENT before the session's first request (a
+     * `/compact` as the very first thing a resumed session does) and on a fixture: the old shape stands.
+     *
+     * In-dialect by construction: these are the bytes the SAME provider already received, so nothing
+     * here reaches a model it had not already reached.
+     */
+    prefixRequest?: ProviderRequest;
+    /**
+     * WS-23: WHY this compaction runs, beyond the pinned `trigger`. `"overflow"` is the reactive recovery
+     * after the provider refused the history as too long: re-sending that same history (the prefix path)
+     * would be refused the same way ("If the input alone already exceeds the model's context window, the
+     * API returns a 400"), so such a compaction always takes the redacted request. Absent means an
+     * ordinary threshold or `/compact` compaction.
+     */
+    reason?: "overflow";
+    /**
+     * WS-23 (reasoning-state, decision 5): the most characters the SUMMARIZER's own request may carry, when
+     * the summarizing model is known to be smaller than the history -- a model switch whose target cannot
+     * hold the conversation, compacting on the target because the source is out of reach, or an overflow.
+     * The oldest part of the summarized window is left out until the rest fits, and the instruction says
+     * so; the retained tail is untouched. Absent: unbounded, as before.
+     */
+    maxInputChars?: number;
+}
+export interface CompactionResult {
+    summary: string;
+    /**
+     * The messages that survive the boundary, in order, ALREADY EXCLUDING anything the summary
+     * replaces. The engine swaps its whole history for `[summary-as-user-message, ...retained]`, so a
+     * controller that returns the full input here has compacted nothing and the engine will say so
+     * rather than silently looping.
+     */
+    retained: ProviderMessage[];
+    /** The reading `contextTokens()` gave BEFORE compaction -- lands on `compact_metadata.pre_tokens`. */
+    preTokens: number;
+    /**
+     * Deferred tools referenced by the retained messages (WS-09 §8.5). Handed to
+     * `registry.onCompaction`, which resets the session's loaded set to `evidenced ∩ still-registered`:
+     * a tool the model can no longer see evidence of having loaded must not stay silently callable.
+     */
+    evidencedToolNames: string[];
+}
+export interface CompactionController {
+    /**
+     * The AUTO trigger. R5-4's own formula is `contextTokens() >= compactionThreshold * limit()`, but
+     * the predicate lives with the controller rather than in the engine so the threshold, its default,
+     * and any hysteresis are one lane's to own and to capture against.
+     *
+     * The engine calls this before each provider call of a turn and NEVER for a manual `/compact`.
+     */
+    shouldCompact(accountant: ContextAccountant): boolean;
+    compact(input: CompactionInput): Promise<CompactionResult>;
+}
+/**
+ * What the engine hands the store when a compaction commits. The dialect turns it into a
+ * `compact_summary` entry plus a `compact_boundary` entry carrying the pinned six-field
+ * `compact_metadata` (derived-shapes-p5 item (f)).
+ *
+ * `retainedCount` rather than the retained messages themselves: the pinned `preserved_messages` names
+ * ALREADY-PERSISTED entries by uuid and relinks them, so the store identifies them from its own
+ * append log instead of re-persisting copies. Re-persisting would double every surviving message in
+ * the transcript a UI renders.
+ */
+export interface CompactBoundaryRecord {
+    trigger: "auto" | "manual";
+    preTokens: number;
+    postTokens?: number;
+    durationMs?: number;
+    summary: string;
+    retainedCount: number;
+}
+/**
+ * What the store hands BACK (fix round 1, M3). The uuids are minted inside the store layer, so this
+ * is the only way the emitted `compact_boundary` frame can carry `preserved_messages` at all -- the
+ * first version returned `void`, which made that field permanently unreachable on the wire while the
+ * DURABLE entry carried it correctly. A host reading the stream could never relink a preserved
+ * segment; only a host re-reading the transcript could.
+ *
+ * `preservedUuids` is empty when nothing was kept, and the frame then OMITS `preserved_messages`
+ * entirely -- absence stays semantic ("compaction summarized everything"), exactly as the pin has it.
+ */
+export interface CompactBoundaryWriteResult {
+    boundaryUuid: string;
+    anchorUuid: string;
+    preservedUuids: string[];
+}
+/**
+ * The spine's test double. Summarizes by concatenating a marker with the message count and keeps the
+ * last `keep` messages -- deterministic, authored-prose-free, and enough for an engine test to prove
+ * the whole sequence ran in order.
+ */
+export declare function fakeCompactionController(opts?: {
+    shouldCompact?: boolean | ((accountant: ContextAccountant) => boolean);
+    keep?: number;
+    summary?: string;
+    evidencedToolNames?: string[];
+    calls?: CompactionInput[];
+    /** Throws instead of compacting -- the failure arm. */
+    fail?: string;
+}): CompactionController;

package/dist/compaction/summarizer.d.ts

@@ -0,0 +1,79 @@
+import type { Provider, ProviderMessage, ProviderRequest } from "../engine.js";
+export declare const WINTER_SUMMARY_INSTRUCTION: string;
+/**
+ * WS-23: the same instruction for the PREFIX-REUSING summary, where it rides as the last user message
+ * after the session's own conversation (so "above", not "below") and the session's tools are still
+ * declared -- declared because removing them would change the cached prefix, which is the whole point.
+ */
+export declare const WINTER_PREFIX_SUMMARY_INSTRUCTION: string;
+/**
+ * WS-23: is this provider request the summariser's, in either shape -- the redacted one (Winter's
+ * instruction as `system`) or the prefix-reusing one (the instruction as the final user message)?
+ * For a scripted double that must answer the summariser differently from the conversation; nothing in
+ * production branches on it.
+ */
+export declare function isCompactionSummaryRequest(req: Pick<ProviderRequest, "system" | "messages">): boolean;
+/** WS-23: appended when the conversation already opens with a summary this compaction carries forward VERBATIM. */
+export declare const CARRIED_SUMMARY_NOTE = "The conversation above begins with an earlier summary, which is kept verbatim; summarize only what happened after it.";
+/**
+ * WS-23: the prefix-reusing request shows the model the WHOLE conversation, including the exchanges the
+ * compaction keeps verbatim after the summary -- the redacted request only ever showed it the part
+ * being replaced. This sentence scopes the summary back to that part, so a compaction does not
+ * restate what stays in context anyway. It rides the appended instruction, so it costs the cache
+ * nothing.
+ */
+export declare function retainedExchangesNote(pairs: number): string;
+/** How much of a tool call's own input is rendered into the summarizer's view of the transcript. */
+export declare const DEFAULT_TOOL_INPUT_PREVIEW_CHARS = 500;
+/**
+ * Winter's instruction, plus the caller's own on a manual `/compact <instructions>` run (and any
+ * context a PreCompact hook forwarded -- the engine has already folded that into the same field).
+ * ATTRIBUTED rather than spliced: the caller's words are the caller's, and a model that mis-follows
+ * them must be readable as having done so.
+ */
+export declare function buildSummaryInstruction(customInstructions: string | null, instruction?: string): string;
+/**
+ * The messages as the summarizer is allowed to see them: `{ role, content }` only, roles narrowed to
+ * user/assistant (the engine's own `tool` role has no provider meaning outside its history), content
+ * flattened to text built from known block types alone. Every other key on the original object --
+ * including any a future provider adds -- is left behind by construction.
+ */
+export declare function redactForSummary(messages: readonly ProviderMessage[], opts?: {
+    toolInputPreviewChars?: number;
+}): ProviderMessage[];
+/**
+ * WS-23 (midconv, live gate on claude-opus-5-5): the redacted request's messages, ENDING WITH A USER
+ * TURN. The summarised window often ends on an assistant reply, and a request that ends there is an
+ * assistant PREFILL, which newer models refuse outright ("This model does not support assistant message
+ * prefill. The conversation must end with a user message.", HTTP 400) -- the fallback summary, the one
+ * that exists for when the prefix request cannot run, then failed too. So the instruction is the final
+ * user turn: the window as it was, then the ask (and nowhere else -- fix round 1). A window that already ends on a user message
+ * gets the same trailing turn (the adapters merge adjacent user messages), so the shape is one rule.
+ * The prefix-reusing request (`summarizeOverPrefix`) already ends with its instruction as a user turn.
+ */
+export declare function summaryRequestMessages(messages: readonly ProviderMessage[], instruction: string): ProviderMessage[];
+/** WS-23 (midconv): the user marker in front of a summarised window that opens on an assistant reply. */
+export declare const SUMMARY_WINDOW_OPENS_MID_CONVERSATION = "[The conversation continues from an earlier point.]";
+export declare class CompactionSummarizerError extends Error {
+}
+/**
+ * One generation on the session provider. Its usage is deliberately NOT recorded into the
+ * accountant: the accountant reports the LAST TURN's window occupancy, and a summarizer call is not
+ * a turn of the conversation -- recording it would leave the trigger reading a number that describes
+ * the compaction rather than the context it was meant to shrink.
+ */
+export declare function summarize(provider: Provider, messages: readonly ProviderMessage[], instruction: string): Promise<string>;
+/**
+ * WS-23: one generation that REUSES the session's own request -- its system blocks, tools, model,
+ * reasoning settings and every message the main loop already sent, byte for byte -- with the
+ * instruction appended as the final user message, the way a byte-exact fork reuses its parent's
+ * prefix. The largest request of a session then reads its prefix from the prompt cache instead of
+ * paying for all of it again (the old shape sent `{messages, system}` with no cache blocks at all).
+ *
+ * Returns `undefined` when the model answered with a tool call despite the instruction: the session's
+ * tools are declared (dropping them, or forcing `tool_choice: none`, would change the cached prefix,
+ * https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching), so the
+ * caller falls back to the redacted, tool-less summary on the same provider and model rather than
+ * running a tool the summariser was never meant to run.
+ */
+export declare function summarizeOverPrefix(provider: Provider, prefixRequest: ProviderRequest, instruction: string): Promise<string | undefined>;

package/dist/context/agent-listing.d.ts

@@ -0,0 +1,39 @@
+import type { ProviderMessage } from "../engine.js";
+import { type AgentListingDeltaAttachment } from "./attachments.js";
+/**
+ * One agent type this session may list -- already resolved and already FILTERED to what the caller
+ * (depth gating, and the deny-rule / required-MCP filters another lane adds) wants advertised. This
+ * module makes no filtering decision of its own.
+ */
+export interface AgentListingEntry {
+    agentType: string;
+    whenToUse: string;
+    /**
+     * claude's `whenToUseLean`, used instead of `whenToUse` when the session's model takes the lean
+     * prompt. HOOK ONLY in this lane: the lean-model rule is another lane's, so `leanModel` below is
+     * never true yet.
+     */
+    whenToUseLean?: string;
+    tools?: readonly string[];
+    disallowedTools?: readonly string[];
+}
+/**
+ * claude's `SSn`, exactly: both lists present -> `tools` minus the disallowed ones (`None` when that
+ * leaves nothing); only `tools` -> `tools` joined (so `["*"]` renders `*`); only `disallowedTools` ->
+ * `All tools except …` in DECLARED order; neither -> `All tools`.
+ */
+export declare function renderAgentToolSpec(entry: Pick<AgentListingEntry, "tools" | "disallowedTools">): string;
+/** claude's `hrt`: `- <type>: <whenToUse> (Tools: <spec>)`. */
+export declare function renderAgentListingLine(entry: AgentListingEntry, leanModel?: boolean): string;
+export interface AgentListingDeltaOptions {
+    /** claude's `Iu(mz(model))` -- whether the session's model takes the lean `whenToUse`. Another lane decides; `false` until then. */
+    leanModel?: boolean;
+    /** claude's `plan !== "pro" && mode === "default"`. Winter has neither a plan tier nor a UI mode, so `true`. */
+    showConcurrencyNote?: boolean;
+}
+/**
+ * claude's `s1t`: the `agent_listing_delta` attachment this history needs now, or `undefined` when
+ * the available set equals what `history` already announced. `history` is the engine's own message
+ * list, which after a compaction is already claude's post-boundary slice.
+ */
+export declare function computeAgentListingDelta(available: readonly AgentListingEntry[], history: readonly ProviderMessage[], opts?: AgentListingDeltaOptions): AgentListingDeltaAttachment | undefined;

package/dist/context/assembler.d.ts

@@ -0,0 +1,46 @@
+import type { RuntimeConfig, Settings } from "@yanlinglabs/winter-agent-sdk";
+import type { SystemPromptAssembler } from "./seam.js";
+import { type PluginOutputStyleSource } from "./output-styles.js";
+export interface SystemPromptAssemblerDeps {
+    /**
+     * The resolved winter home. Omitted resolves from `SystemPromptInput.env` (so `<PREFIX>HOME` is
+     * honoured per session, not per process). Tests pass an mkdtemp directory here rather than
+     * touching a real home.
+     */
+    home?: string;
+    /**
+     * A LIVE GETTER over the resolved effective settings, read afresh on every `assemble()`.
+     *
+     * A getter and not a value, deliberately: the product rule (WS-11 §5, and Norma's shipped
+     * settings-watcher convention) is that no setting may require a restart to take effect. Handing
+     * the assembler a settings SNAPSHOT at construction would make `outputStyle`, `autoMemoryEnabled`,
+     * `autoMemoryDirectory` and `plansDirectory` frozen for the life of a session, and the failure
+     * would be invisible -- the assembler would keep working, just with stale values.
+     */
+    settings?: () => Settings | undefined;
+    /**
+     * WS-21 §6.3 item 1 (fix round 2): the session's ENABLED plugins that ship an `output-styles/`
+     * directory. A plain VALUE, not a live getter like `settings` above -- a session's loaded-plugin
+     * set is resolved once per incarnation (production-wiring.ts's own precedent for skills/agents/
+     * MCP: plugins are not something a settings-watcher hot-reloads mid-session), so there is nothing
+     * to re-read on a later `assemble()` call. Omitted means no `<plugin>:<style>` name ever resolves,
+     * exactly like every pre-fix-round-2 caller.
+     */
+    pluginOutputStyles?: readonly PluginOutputStyleSource[];
+}
+/**
+ * Phase 5 residual round (T8 re-review NEW-1): "would an output style apply at all?", for a caller
+ * that needs the answer WITHOUT assembling a prompt.
+ *
+ * `production-wiring.ts` resolves the style a second time to report RULING P5-G's downgrade as an
+ * operator warning, and had no equivalent of the `region.authored` guard below -- so with a
+ * caller-supplied `systemPrompt` it told the operator the style "has been applied as an ADDITION"
+ * when it was not applied in any form.
+ *
+ * EXPORTED RATHER THAN HAND-MIRRORED. The condition is one line today ("a string or an array
+ * replaces the prompt"), and one line is exactly what gets copied and then drifts -- this codebase
+ * has four hand-mirrored copies of one trust predicate already, kept in step only by a tripwire
+ * test. One implementation, two callers, no drift possible.
+ */
+export declare function isAuthoredPromptRegion(systemPrompt: RuntimeConfig["systemPrompt"]): boolean;
+export declare function createSystemPromptAssembler(deps?: SystemPromptAssemblerDeps): SystemPromptAssembler;

package/dist/context/attachments.d.ts

@@ -0,0 +1,104 @@
+import type { ProviderMessage } from "../engine.js";
+/**
+ * One attachment payload, exactly as the transcript stores it (`entry.attachment`). Open-ended: the
+ * three types below are this lane's; any other `type` is carried verbatim and rendered only when a
+ * renderer is registered for it.
+ */
+export interface AttachmentPayload {
+    type: string;
+    [key: string]: unknown;
+}
+/** claude's `agent_listing_delta` (`s1t`): what the Agent tool can spawn, as a delta over what the history already announced. */
+export interface AgentListingDeltaAttachment extends AttachmentPayload {
+    type: "agent_listing_delta";
+    addedTypes: string[];
+    addedLines: string[];
+    removedTypes: string[];
+    isInitial: boolean;
+    showConcurrencyNote: boolean;
+}
+/** claude's `skill_listing` (`Urn`): the skills not yet sent this session. `names` seeds the sent set on resume. */
+export interface SkillListingAttachment extends AttachmentPayload {
+    type: "skill_listing";
+    content: string;
+    skillCount: number;
+    isInitial: boolean;
+    names: string[];
+}
+/** claude's `date_change` (`alr`): the local date moved past the one the session's context was built with. */
+export interface DateChangeAttachment extends AttachmentPayload {
+    type: "date_change";
+    newDate: string;
+}
+export declare const AGENT_LISTING_INITIAL_HEADER = "Available agent types for the Agent tool:";
+export declare const AGENT_LISTING_ADDED_HEADER = "New agent types are now available for the Agent tool:";
+export declare const AGENT_LISTING_REMOVED_HEADER = "The following agent types are no longer available:";
+/** claude's `s$`: appended after a "no longer available" section. */
+export declare const AMBIENT_CONTEXT_SENTENCE = "This is ambient context \u2014 do not narrate it to the user unless they ask or it is directly relevant to their request.";
+/** Appended to the INITIAL listing only, when `showConcurrencyNote` is set. */
+export declare const AGENT_CONCURRENCY_SENTENCE = "When you launch multiple agents for independent work, send them in a single message with multiple tool uses so they run concurrently.";
+export declare const SKILL_LISTING_HEADER = "The following skills are available for use with the Skill tool:";
+export declare function dateChangeText(newDate: string): string;
+/** claude's attachment wrapper (`Qa`). Nothing is added around it and nothing after it. */
+export declare function wrapSystemReminder(body: string): string;
+/** A renderer returns the UNWRAPPED body, or `undefined` when the attachment has nothing to say. */
+export type AttachmentRenderer = (attachment: AttachmentPayload) => string | undefined;
+/**
+ * SDK 0.0.16 Lane N: `wrap: false` for the ONE attachment family claude does not wrap. Its
+ * `queued_command` attachments (a task notification delivered mid-turn) are rendered as a BARE user
+ * text block carrying their own `[SYSTEM NOTIFICATION - NOT USER INPUT]` preamble instead of the
+ * `<system-reminder>` envelope every other attachment type gets (traced in the pinned binary: the
+ * queued-command branch of its request builder calls its origin-aware renderer directly, never the
+ * reminder wrapper). Defaults to `true`, so every type registered before this option existed is
+ * unchanged.
+ */
+export interface AttachmentRendererOptions {
+    wrap?: boolean;
+    /**
+     * WS-23: the attachment may ride as a MID-CONVERSATION `role: "system"` message on a model whose row
+     * documents them (`ModelWireFeatures.midConversationSystem`), instead of as user-turn text. OPT-IN,
+     * and only for text Winter itself AUTHORS: the vendor is explicit that a system message gives its
+     * text operator authority and must not carry "text from outside the conversation"
+     * (https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#limitations).
+     * So the agent and skill listings (they fold in project, user and plugin descriptions verbatim) and
+     * task notifications (subagent output) stay user text; `date_change` is the built-in that qualifies.
+     */
+    systemRole?: boolean;
+}
+/**
+ * Registers (or replaces) the renderer for one attachment type. Another lane's types (task
+ * notifications, plan-mode reminders) plug in here; the engine and the resume path then carry them
+ * with no further change.
+ */
+export declare function registerAttachmentRenderer(type: string, renderer: AttachmentRenderer, options?: AttachmentRendererOptions): void;
+/** WS-23: whether this attachment's renderer opted into the mid-conversation `system` role. */
+export declare function isSystemRoleAttachment(attachment: AttachmentPayload): boolean;
+/** The wrapped model-facing text for an attachment, or `undefined` when there is none (an unknown type included). */
+export declare function renderAttachment(attachment: AttachmentPayload): string | undefined;
+/** The history message for an attachment, or `undefined` when it renders to nothing (it is then not appended at all). */
+export declare function attachmentMessage(attachment: AttachmentPayload): ProviderMessage | undefined;
+export declare function isAttachmentMessage(message: ProviderMessage): message is ProviderMessage & {
+    meta: {
+        attachment: AttachmentPayload;
+    };
+};
+/** Every attachment payload in `messages`, in order. The engine's history IS claude's post-compaction slice (`Ml`). */
+export declare function attachmentsIn(messages: readonly ProviderMessage[]): AttachmentPayload[];
+/**
+ * claude's `s1t` fold: the agent types the history has already announced. A delta's `addedTypes`
+ * count only when it carries an `addedLines` array (claude's own guard); `removedTypes` always remove.
+ */
+export declare function announcedAgentTypes(messages: readonly ProviderMessage[]): Set<string>;
+/** claude's `alr` fold: whether a `date_change` for `date` is already in the history. */
+export declare function dateChangeAnnounced(messages: readonly ProviderMessage[], date: string): boolean;
+/**
+ * claude's `vlr` resume seed for the skill listing: the names every persisted `skill_listing` sent,
+ * and whether a legacy entry without `names` asks the next listing to be suppressed (claude's
+ * `suppressNext`).
+ */
+export declare function skillListingResumeSeed(messages: readonly ProviderMessage[]): {
+    names: string[];
+    suppressNext: boolean;
+};
+/** claude's `tcn`: the LOCAL calendar date, `YYYY-MM-DD`. */
+export declare function localDateString(now?: Date): string;

package/dist/context/dynamic-sections.d.ts

@@ -0,0 +1,31 @@
+export declare const ENVIRONMENT_HEADING = "# Environment";
+export declare const ENVIRONMENT_LEAD_IN = "You have been invoked in the following environment: ";
+/** Winter's product line (claude's equivalent lines describe its own CLI). */
+export declare const WINTER_PRODUCT_LINE = "Winter runs this session as an agent runtime on behalf of a host application; the host decides how your output is shown to the user.";
+export interface EnvironmentInput {
+    cwd: string;
+    isGitRepo: boolean;
+    platform: string;
+    /** The raw `$SHELL` value; reduced to `zsh` / `bash` the way claude reduces it. */
+    shell: string;
+    /** `<os type> <os release>`, e.g. `Darwin 25.6.0`. */
+    osVersion: string;
+    additionalDirectories?: readonly string[];
+    /** The model id this session generates with. Absent: no model line. */
+    model?: string;
+    /** The model's display name, when the catalog knows one. */
+    modelDisplayName?: string;
+    /** The model's knowledge cutoff, when known. Winter's catalog carries none today, so the line is normally absent. */
+    knowledgeCutoff?: string;
+}
+/** claude's `GEe`: the shell as `zsh`, `bash`, the raw value, or `unknown`. */
+export declare function shellName(raw: string): string;
+/** The whole section for the system prompt's dynamic half (claude's `mHn`). */
+export declare function renderEnvironmentSection(input: EnvironmentInput): string;
+/** `excludeDynamicSections`, static half (claude's `fHn`): the model and product lines only. */
+export declare function renderStaticEnvironmentSection(input: Pick<EnvironmentInput, "model" | "modelDisplayName" | "knowledgeCutoff">): string;
+/**
+ * `excludeDynamicSections`, userContext half (claude's `gHn` through `jEe`): the machine facts under
+ * the lead-in, WITHOUT the heading -- the heading's text becomes the userContext key `Environment`.
+ */
+export declare function renderEnvironmentContextValue(input: EnvironmentInput): string;

package/dist/context/git-fixture.d.ts

@@ -0,0 +1,18 @@
+export interface GitFixture {
+    /** The main checkout's working-tree root. */
+    main: string;
+    /** A linked worktree of the same repository (`git worktree add`), at a path OUTSIDE `main`. */
+    worktree: string;
+    /** The mkdtemp root holding both -- remove this to clean up. */
+    root: string;
+}
+/** Runs git with every machine-level influence (hooks, identity, signing, config files) neutralised. */
+export declare function hermeticGit(cwd: string, args: string[], home: string, hooksPath: string): string;
+/**
+ * A real repository with one commit plus a real linked worktree, both under one mkdtemp root.
+ *
+ * The worktree is placed as a SIBLING of the main checkout, not beneath it: a worktree nested
+ * inside the main tree would make the common root an ancestor of the worktree by accident, and the
+ * WINTER.md boundary test would pass for the wrong reason.
+ */
+export declare function makeGitFixture(): GitFixture;

package/dist/context/git-status.d.ts

@@ -0,0 +1,16 @@
+/** Winter's snapshot caveat (claude's sentence says the same thing in its own words). */
+export declare const GIT_STATUS_CAVEAT = "This git status was captured when the session began; it is a snapshot and does not change as the conversation goes on.";
+/** claude's `hde`. */
+export declare const GIT_STATUS_MAX_CHARS = 2000;
+/**
+ * The `gitStatus` value for `cwd`, or `undefined` when there is none. Never throws. `env` is for
+ * tests (a hermetic git config); the engine runs git with the process environment, as the
+ * instructions-file and memory-key git reads already do.
+ */
+export declare function computeGitStatus(cwd: string, env?: Record<string, string | undefined>): Promise<string | undefined>;
+/**
+ * The kill switch (claude's `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS`, Winter's `<PREFIX>DISABLE_GIT_INSTRUCTIONS`)
+ * over the `includeGitInstructions` setting (default true). An explicit env value wins either way,
+ * as claude's `VU` does: a truthy value disables, a falsy one ("0"/"false"/"no"/"off") enables.
+ */
+export declare function gitInstructionsEnabled(envValue: string | undefined, includeGitInstructions: unknown): boolean;

package/dist/context/imports.d.ts

@@ -0,0 +1,22 @@
+export type ImportTier = "user" | "project" | "local";
+export interface ExpandImportsInput {
+    content: string;
+    /** The file this content came from -- imports resolve relative to ITS directory. */
+    filePath: string;
+    tier: ImportTier;
+    /** `null` when there is no repository (a bare `cwd`); a project/local import then never resolves. */
+    projectRoot: string | null;
+    /** Default 5 (F17 / the plan brief). */
+    maxDepth?: number;
+}
+export interface ExpandImportsResult {
+    content: string;
+    /** Absolute paths of every import this expansion DROPPED (out-of-scope for a project/local file). Depth-capped and missing imports are not reported here -- they are ordinary "nothing to substitute" outcomes, not scope refusals. */
+    dropped: string[];
+}
+/**
+ * Expand every `@import` token in `input.content`, recursively, up to `maxDepth` levels. Returns
+ * the expanded content plus the absolute paths of every import DROPPED for being out of a
+ * project/local file's scope (never the depth-capped or missing ones -- see the module header).
+ */
+export declare function expandImports(input: ExpandImportsInput): ExpandImportsResult;

package/dist/context/injection.d.ts

@@ -0,0 +1,53 @@
+/** Appended to a block that was cut short, so the model knows it is reading a prefix. */
+export declare const TRUNCATION_MARKER = "\n[\u2026truncated]";
+/**
+ * Cap to `maxBytes` UTF-8 bytes on a valid boundary. A multibyte character split by the cut
+ * degrades to U+FFFD rather than a lone surrogate (`Buffer.toString` guarantees this), which keeps
+ * the result a well-formed string every JSON encoder on the path can carry.
+ *
+ * THE REPLACEMENT CHARACTER CAN PUSH THE RESULT BACK OVER THE CAP, which is why the trailing
+ * U+FFFD is dropped when it does. Cutting mid-character consumes 1-3 bytes of the original and
+ * emits a 3-byte U+FFFD in their place, so a naive `subarray(0, maxBytes).toString()` can re-encode
+ * to `maxBytes + 2` -- Norma's shipped twin has exactly this hole. It is small, but a cap that only
+ * approximately holds is not a cap, and this is the primitive every other ceiling in this lane is
+ * expressed in terms of. Found by the fixture, not by reading: the assertion was written as
+ * "<= maxBytes" and failed at 7 bytes for a 5-byte budget.
+ */
+export declare function capBytes(text: string, maxBytes: number): {
+    text: string;
+    truncated: boolean;
+};
+/**
+ * Defuses a literal `<system-reminder>` / `</system-reminder>` inside untrusted file content.
+ *
+ * Deliberately does NOT collapse newlines (Norma's engine-side twin does, for tool results): these
+ * are real multi-line markdown documents, and flattening an index or an instruction file would make
+ * it unreadable. Only the tag itself is a containment problem here.
+ */
+export declare function neutralizeReminderTags(text: string): string;
+/**
+ * Wraps a body as a labelled, harness-injected block. `label` is authored text (a caption naming
+ * the file and why it is here); `body` is file content and is neutralised before wrapping.
+ */
+export declare function systemReminder(label: string, body: string): string;
+/**
+ * Read a UTF-8 file, capped at `maxBytes`. `null` for missing / unreadable / not-a-regular-file /
+ * empty -- all four are "there is nothing to inject", which is not an error condition.
+ */
+export declare function readCapped(path: string, maxBytes: number): string | null;
+/**
+ * Read a UTF-8 file WHOLE, no byte ceiling. WS-21 §6.3 item 10 (F7): claude does not truncate its
+ * own instructions file, and winter-md.ts stopped capping the brand's own instructions basename to
+ * match. This is a
+ * DELIBERATE exception to this module's own rule (1) above -- the instructions file is re-sent every
+ * request just like a capped block is, but parity with claude wins here, the same way it already won
+ * for the skill description cap. Same "nothing to inject" contract as `readCapped`: missing,
+ * unreadable, not-a-regular-file or empty all yield `null`, never a thrown error.
+ */
+export declare function readWhole(path: string): string | null;
+/**
+ * Read a UTF-8 file capped at `maxLines` AND `maxBytes`, WHICHEVER HITS FIRST (WS-05 §11's
+ * memory-index rule; lines are counted before bytes so a 25 KB budget cannot smuggle in a
+ * 10 000-line file). `null` on the same four "nothing to inject" cases as `readCapped`.
+ */
+export declare function readCappedLinesAndBytes(path: string, maxLines: number, maxBytes: number): string | null;

package/dist/context/memory-key.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Norma's `_global`/`_assistant` product buckets (a no-project bucket and the shared dream bucket).
+ * WS-11 §3 and WS-05 §11 both pin them as PRODUCT EXTENSIONS that are never silently injected into
+ * a Code session. Winter's assembler has no code path that can produce either: the pinned
+ * project-key sanitiser maps every non-alphanumeric character to `-`, so a key can never begin with
+ * `_`. This constant exists so that fact is assertable rather than merely true.
+ */
+export declare const RESERVED_MEMORY_KEYS: readonly string[];
+/**
+ * TEST-ONLY. A suite that builds throwaway repositories at reused paths, or that wants to prove the
+ * cache is not the thing making an assertion pass, must be able to clear it. Production never calls
+ * this.
+ */
+export declare function _clearMemoryKeyCacheForTests(): void;
+/**
+ * The `<memory-key>` segment for `cwd`: the git-common-root-derived key, then the P1-N env
+ * override. `env` is injectable so tests never read the real process environment.
+ */
+export declare function memoryProjectKeyFor(cwd: string, env?: Record<string, string | undefined>): string;
+export interface MemoryDirInput {
+    cwd: string;
+    /** The `~/.winter` root (WINTER_HOME-aware; the caller resolves it). */
+    home: string;
+    /**
+     * WS-21 §3.7: the shared runtime home's durable-paths root (`config.storeHome`), preferred over
+     * `home` when present -- code-mode auto-memory is a DURABLE path (spec §3.7's own list), so it
+     * lives under `sdk/projects/<key>/memory`, not the per-run folder `home` names once the router
+     * links `buildRunHome`. Absent (every incarnation before then, or a non-router host) falls back
+     * to `home`, byte-identical to pre-WS-21 behaviour.
+     */
+    storeHome?: string;
+    env?: Record<string, string | undefined>;
+    /**
+     * `Settings.autoMemoryDirectory` (or a host-supplied `SystemPromptInput.memoryDir`) -- REPLACES
+     * the computed path entirely, with no further per-project nesting beneath it, mirroring the
+     * pinned relocatable-directory setting. Whitespace-only counts as ABSENT: a settings.json holding
+     * `"autoMemoryDirectory": ""` must not resolve memory to the home directory itself.
+     *
+     * The pinned key is ignored when it comes from PROJECT settings (its own declaration says so, for
+     * security) -- that filter is `OVERLAY_NEVER_KEYS` in the settings layer, upstream of here. This
+     * module consumes whatever survived it and re-litigates nothing.
+     */
+    override?: string;
+}
+/** The absolute auto-memory directory for a session. Pure path computation -- creates nothing. */
+export declare function memoryDirFor(input: MemoryDirInput): string;

package/dist/context/memory.d.ts

@@ -0,0 +1,28 @@
+import { type Settings } from "@yanlinglabs/winter-agent-sdk";
+export declare const MEMORY_INDEX_BASENAME = "MEMORY.md";
+/**
+ * The compatibility-profile load cap, pinned by WS-05 §11 and WS-11 §3: the first 200 lines OR
+ * 25 KB of `MEMORY.md`, whichever hits first. Binary KB (25 * 1024), matching Norma's shipped
+ * numbers this is ported from. Version-drift tested; behaviour, not a format guarantee.
+ */
+export declare const MEMORY_INDEX_MAX_LINES = 200;
+export declare const MEMORY_INDEX_MAX_BYTES: number;
+/**
+ * `Settings.autoMemoryEnabled`. UNSET MEANS ENABLED -- the key is an opt-OUT (WS-11 §3:
+ * "hosted/hermetic deployments MAY disable automatic memory"), so the absence of a settings file
+ * cannot be read as "no memory". Only a literal `false` disables; a JSON settings file can hold
+ * anything, and a truthy-but-not-boolean value must not fall through to disabled by accident.
+ */
+export declare function autoMemoryEnabled(settings: Settings | undefined): boolean;
+/** The capped index for a memory directory, or `null` when there is nothing to inject. */
+export declare function loadMemoryIndex(memoryDir: string): string | null;
+/** claude's section heading for the auto-memory guidance. */
+export declare const AUTO_MEMORY_HEADING = "# auto memory";
+/**
+ * The system prompt's `# auto memory` section: the heading, a blank line, Winter's own guidance
+ * (which names the directory). Injected even with no `MEMORY.md` on disk -- a fresh project has
+ * nothing to recall but every reason to know it CAN save something.
+ */
+export declare function renderAutoMemorySection(memoryDir: string, instructionsFile?: string): string;
+/** `excludeDynamicSections`: the same guidance as the userContext value under the key `auto memory` (claude's `jEe` strips the heading). */
+export declare function renderAutoMemoryContextValue(memoryDir: string, instructionsFile?: string): string;

package/dist/context/minimal-prompt.d.ts

@@ -0,0 +1,5 @@
+/** R5-9's ceiling. Asserted, not aspirational -- a "minimal" prompt that grew is no longer minimal. */
+export declare const MINIMAL_PROMPT_MAX_LINES = 20;
+/** Bump on any edit to the text below. Reported as `AssembledPrompt.presetVersion`. */
+export declare const MINIMAL_PROMPT_VERSION = "winter_minimal@1";
+export declare const MINIMAL_PROMPT: string;