@yanlinglabs/winter-agent-runtime 0.0.27

package/dist/context/output-styles.d.ts

@@ -0,0 +1,68 @@
+import { type BrandProfile, type SettingSource } from "@yanlinglabs/winter-agent-sdk";
+export declare const DEFAULT_OUTPUT_STYLE_NAME = "default";
+/** Per-style body ceiling. A style rides every request, so it needs a bound like every other injected file. */
+export declare const OUTPUT_STYLE_MAX_BYTES: number;
+export interface ResolvedOutputStyle {
+    /** Always the filename stem (or the built-in's name) -- never the frontmatter, so `list` and `resolve` cannot disagree. */
+    name: string;
+    description: string;
+    /** Injection-safe and capped for file styles; a trusted constant for built-ins. */
+    body: string;
+    /**
+     * `true` (the default) keeps the base prompt's coding-instructions section; `false` drops it. The
+     * style's body always lands in a dynamic section, in either case (fix round 4/I-F) -- this field
+     * never decides whether the body is added, only whether the ONE base section is cut.
+     */
+    keepCodingInstructions: boolean;
+    source: "project" | "user" | "builtin" | "plugin";
+    /** True when the file asked to DROP the coding-instructions section and the project-tier trust rule downgraded it to keeping it. */
+    replacementDowngraded: boolean;
+}
+/**
+ * The four built-ins. `default` is RESERVED: an empty body that is never injected, so selecting it
+ * is byte-identical to selecting nothing.
+ */
+export declare const BUILTIN_OUTPUT_STYLES: readonly ResolvedOutputStyle[];
+export declare const BUILTIN_OUTPUT_STYLE_NAMES: readonly string[];
+/** A minimal projection of `plugins/bundle.ts`'s `PluginBundle` -- only the fields output-style resolution needs, so this file never depends on the plugin loader's own shape. */
+export interface PluginOutputStyleSource {
+    name: string;
+    outputStylesPath?: string;
+    /**
+     * Fix round 5: a manifest `outputStyles` override -- see `PluginBundle.outputStylesPaths`'s own
+     * comment for why a real bundle never sets both this and `outputStylesPath` together (the override
+     * SHADOWS the default directory at load time). Each entry may be a directory (scanned the same way
+     * `outputStylesPath` is) or a single style file, matching claude's own `Tb`
+     * (`requireDirectory:false` for `output-styles`, dump-confirmed).
+     */
+    outputStylesPaths?: readonly string[];
+}
+export interface OutputStyleLookup {
+    cwd: string;
+    /** The resolved winter home (`~/<brand.homeDirName>` by default). */
+    home: string;
+    /** P7a (D19): the session's brand -- the project dot-dir the project tier is read from. Omitted = `WINTER_BRAND`. */
+    brand?: Pick<BrandProfile, "projectDirName">;
+    /** Omitted means all three tiers (the pinned default). */
+    settingSources?: readonly SettingSource[];
+    /** RULING P5-A's host-declared trust bit. Only `true` lets a PROJECT-tier style drop the coding-instructions section. */
+    trustedWorkspace?: boolean;
+    /**
+     * WS-21 §6.3 item 1 (fix round 2): the session's ENABLED plugins, projected to just the two
+     * fields a `<plugin>:<style>` lookup needs. Omitted (every pre-fix-round-2 caller) means no
+     * plugin ever resolves -- a qualified name simply falls through to `null`, matching what happened
+     * before this field existed.
+     */
+    pluginOutputStyles?: readonly PluginOutputStyleSource[];
+}
+/**
+ * Resolve a style by name: a `<plugin>:<style>` qualified name resolves against that plugin's own
+ * `output-styles/` directory (WS-21 §6.3 item 1) regardless of `settingSources` -- a plugin is
+ * DELIBERATELY NOT source-gated anywhere else in this codebase either (subagents/definitions.ts's
+ * own header states the identical reasoning: a plugin is loaded because the HOST or the USER
+ * decided to, a decision already made outside the repository, so gating it on workspace trust would
+ * make plugin behaviour depend on which directory the session happens to be in). Otherwise: project
+ * (source-gated) > user (source-gated) > built-in. Never throws; `null` means the name resolves to
+ * nothing, which the assembler treats as "no style".
+ */
+export declare function resolveOutputStyle(name: string, lookup: OutputStyleLookup): ResolvedOutputStyle | null;

package/dist/context/plan-mode.d.ts

@@ -0,0 +1,29 @@
+/**
+ * FIXED. States the restriction the permission engine enforces, so a denial is never a surprise.
+ */
+export declare const PLAN_MODE_ENFORCEMENT: string;
+/**
+ * REPLACEABLE. Winter's own answer to "what makes a good plan", used when the host supplies none.
+ */
+export declare const DEFAULT_PLAN_BODY: string;
+/** FIXED. The ExitPlanMode contract, plus where a written plan belongs. */
+export declare const PLAN_MODE_PROTOCOL: string;
+export interface PlanModeInput {
+    /** Where a plan file belongs when one is written. `RuntimeConfig.plansDirectory` / `Settings.plansDirectory`, default `<brand.projectDirName>/plans`. */
+    plansDirectory: string;
+    /** The host's replacement for the middle section (`planModeInstructions` on the wire). Whitespace-only counts as absent. */
+    hostPlanBody?: string;
+    /**
+     * P7a fix r1 (Minor-1): what a REFUSED `plansDirectory` falls back to.
+     *
+     * `renderablePlansDirectory` refuses a value that fails RULING P5-L's alphabet and substitutes
+     * this. It used to be `DEFAULT_PLANS_DIRECTORY` — Winter's own `<dot-dir>/plans` — under every
+     * brand, so the one path that reaches the model when a project's setting is malformed named a
+     * directory a reuser's product does not have. The caller (`context/assembler.ts`) already derives
+     * the NORMAL value from the session's profile; this is the same string.
+     */
+    plansDirectoryFallback?: string;
+}
+/** The value as it may be rendered into `system`: the caller's, if it is a plain path; otherwise the pinned default. */
+export declare function renderablePlansDirectory(raw: string, fallback: string): string;
+export declare function renderPlanModeBlock(input: PlanModeInput): string;

package/dist/context/request-layout.d.ts

@@ -0,0 +1,138 @@
+import type { ContentBlock, ProviderMessage, ProviderToolSpec } from "../engine.js";
+import type { SystemPromptBlock } from "@yanlinglabs/winter-provider-runtime";
+/** One userContext / systemContext entry, in the order it is rendered. */
+export type ContextEntry = readonly [key: string, value: string];
+/**
+ * claude's `mbt` text for a userContext map, or `undefined` when the map is empty (claude then
+ * prepends nothing). Exactly one trailing newline; the second one the wire shows comes from the
+ * merge with the prompt (`Noe`).
+ */
+export declare function renderUserContext(entries: readonly ContextEntry[]): string | undefined;
+/** claude's `pbt` systemContext part: `key: value` lines. `undefined` when there are none. */
+export declare function renderSystemContext(entries: readonly ContextEntry[]): string | undefined;
+/**
+ * claude's `VEe` for Winter's two halves. With a dynamic boundary (Winter's authored prompt, the
+ * preset, or a caller array that names one) the static half is one `global` block and the dynamic
+ * half -- systemContext appended last -- one `org` block. Without a boundary (a caller string, or a
+ * caller array with none) everything is one `org` block. Empty parts are dropped (`filter(Boolean)`).
+ */
+export declare function buildSystemBlocks(input: {
+    staticParts: readonly string[];
+    dynamicParts: readonly string[];
+    systemContext?: string;
+    hasBoundary: boolean;
+}): SystemPromptBlock[];
+/** The `system` string equivalent of a block list (what a block-unaware provider receives). */
+export declare function joinSystemBlocks(blocks: readonly SystemPromptBlock[]): string;
+/**
+ * claude's `SJn` (reorderAttachmentsForAPI). WS-23: `stays` names attachments that keep their HISTORY
+ * position instead of bubbling up -- a system-role reminder must follow the user turn that triggered
+ * it, which is exactly where the engine appended it.
+ */
+export declare function reorderAttachments(messages: readonly ProviderMessage[], stays?: (message: ProviderMessage) => boolean): ProviderMessage[];
+/**
+ * claude's `NMe`: a reminder that must never be folded into a tool result (its poll-event
+ * deliveries). Ported literally; Winter produces neither prefix today, so this only keeps a
+ * claude-written transcript's shape intact on resume.
+ */
+export declare function isSmooshExempt(text: string): boolean;
+type ToolResultBlock = Extract<ContentBlock, {
+    type: "tool_result";
+}>;
+type TextBlock = Extract<ContentBlock, {
+    type: "text";
+}>;
+/**
+ * claude's `IMe`: fold trailing text blocks INTO a tool result. `null` when the result carries a
+ * `tool_reference` (claude refuses to fold into those).
+ */
+export declare function foldTextIntoToolResult(result: ToolResultBlock, texts: TextBlock[]): ToolResultBlock | null;
+/**
+ * The live request's message list: `history` with the index-0 context prepended, attachments
+ * reordered and consecutive user-role messages merged, exactly as the pinned binary builds it.
+ * Never mutates `history`. Assistant messages pass through untouched (their own merge is the
+ * adapters' business, as before).
+ */
+export declare function buildRequestMessages(history: readonly ProviderMessage[], userContextText?: string, opts?: {
+    systemReminders?: boolean;
+    effort?: EffortMarkerPlan;
+    toolChanges?: ToolChangeRendering;
+}): ProviderMessage[];
+/**
+ * WS-23 (midconv): which `tool_changes` entries this request renders -- the active epoch's, by identity
+ * (the engine's own history objects). Absent: every bookkeeping entry is dropped (today's layout).
+ */
+export interface ToolChangeRendering {
+    render: ReadonlySet<ProviderMessage>;
+}
+/** WS-23: the per-message effort plan `buildRequestMessages` lays out -- see `withEffortMarkers`. */
+export interface EffortMarkerPlan {
+    /** The level in force before any marker: the frozen top-level value, or the model's default when none is sent. */
+    initial: string;
+    /** The level for the turn being generated now. */
+    live: string;
+    /** Levels the target row can take. */
+    accepts: (effort: string) => boolean;
+    /**
+     * WS-23 (reasoning-state): whether an assistant message is the TARGET model's own. A per-message effort
+     * level is a cache quirk of one model -- a vocabulary and a cached prefix of its own -- so only its own
+     * replies' levels become markers; another model's reply is read as un-annotated (no marker). Absent:
+     * every reply counts (the pre-WS-23 reading, and a session with no provider identity).
+     */
+    owns?: (message: ProviderMessage) => boolean;
+}
+/**
+ * `ordered` (the history AFTER the attachment reorder and BEFORE the user-turn merge) with an
+ * effort-only `system` marker before every human turn whose level differs from the one in force before
+ * it. Run before the merge on purpose (fix round 1, I2): after it, a prompt that follows an INTERRUPTED
+ * tool round is folded into the `tool` message ahead of it and is no longer recognisable as a turn
+ * start -- the change would silently not apply while the transcript recorded it. A marker is never
+ * merged, so it also keeps that prompt as its own user entry.
+ *
+ * PLACEMENT: before the turn's attachments when they bubbled up to the previous assistant reply (so
+ * the common case keeps its merged user entry), otherwise directly before the prompt. A turn with no
+ * annotated reply (a host-supplied or pre-WS-23 history) is left alone, and a level the row cannot take
+ * gets no marker -- both deterministic, so still byte-stable.
+ */
+export declare function withEffortMarkers(ordered: readonly ProviderMessage[], plan: EffortMarkerPlan): ProviderMessage[];
+/**
+ * WS-23: every tool name a ToolSearch result in `history` surfaced (`tool_result.loadedTools`, advertised
+ * names). A deferred tool in this set is referenced somewhere in the history, so it can stay declared
+ * `defer_loading: true`; a loaded tool outside it would be invisible to the model and is sent plainly.
+ */
+export declare function referencedToolNames(history: readonly ProviderMessage[], modelKey?: string | null): Set<string>;
+/**
+ * The top-level effort the session sent, read back off a history: the newest ANNOTATED assistant
+ * message's own `effort` (absent means the session sent none at the top level). `undefined` when no
+ * assistant message is annotated at all -- nothing to restore.
+ */
+export declare function frozenEffortFromHistory(history: readonly ProviderMessage[], owns?: (message: ProviderMessage) => boolean): {
+    value: string | undefined;
+} | undefined;
+/**
+ * What a session last sent: the exact system blocks, the userContext entries behind its index-0
+ * message, and the tool specs. A byte-exact fork (a later lane) reuses these verbatim; nothing in
+ * this lane reads them.
+ */
+export interface SessionRequestLayout {
+    system?: string;
+    systemBlocks: SystemPromptBlock[];
+    userContext: ContextEntry[];
+    tools: ProviderToolSpec[];
+}
+/** Records the layout of the request a session (or one of its agents) just sent. */
+export declare function recordSessionRequestLayout(sessionId: string, agentId: string | undefined, layout: SessionRequestLayout): void;
+/** The layout a session (or one of its agents) last sent, or `undefined` before its first request. */
+export declare function getSessionRequestLayout(sessionId: string, agentId?: string): SessionRequestLayout | undefined;
+/** Drops a session's (or agent's) recorded layout -- the engine's teardown calls this. */
+export declare function clearSessionRequestLayout(sessionId: string, agentId?: string): void;
+/** The engine registers its session-context memo's clear hook here (and withdraws it at teardown). */
+export declare function registerSessionContextReload(sessionId: string, agentId: string | undefined, clear: () => void): void;
+export declare function unregisterSessionContextReload(sessionId: string, agentId?: string): void;
+/**
+ * EXPLICIT RELOAD: drop a live session's memoized userContext/systemContext so its next request
+ * re-reads the instructions files, the memory index and the git snapshot (claude does the same on a
+ * `reload_claude_md`-style request). `false` when no such session is running.
+ */
+export declare function reloadSessionContext(sessionId: string, agentId?: string): boolean;
+export {};

package/dist/context/rules.d.ts

@@ -0,0 +1,63 @@
+import type { BrandProfile } from "@yanlinglabs/winter-agent-sdk";
+import type { AttachmentProducer, ProviderMessage } from "../engine.js";
+import { type AttachmentPayload } from "./attachments.js";
+export type RuleSettingSource = "user" | "project" | "local";
+export interface LoadedRule {
+    /** Absolute path of the rule `.md` file. */
+    path: string;
+    tier: "user" | "project";
+    /** The rule's body, frontmatter stripped, trimmed. */
+    content: string;
+    /** Present (and non-empty) iff this is a CONDITIONAL rule. Raw glob strings, as authored. */
+    paths?: string[];
+    /**
+     * PROJECT tier only: the parent of the project dot-dir (brand.projectDirName) this rule file was
+     * discovered under, fixed at load time (F17's "relative to the parent of the project dot-dir").
+     * Absent for a user-tier rule, which resolves against whatever `originalCwd` `ruleMatches` is
+     * called with instead.
+     */
+    projectBase?: string;
+}
+export interface LoadRulesInput {
+    /** The winter home (`<PREFIX>HOME`, i.e. the shared runtime home under WS-21). */
+    home: string;
+    cwd: string;
+    /** The repository root, or `null` outside one. Project rules load only when this is set. */
+    projectRoot: string | null;
+    /** Omitted means every tier loads (loadRules has no separate "all tiers" default of its own --
+     *  every caller threads the session's resolved settingSources explicitly). */
+    sources: readonly RuleSettingSource[];
+    brand: Pick<BrandProfile, "projectDirName">;
+}
+/**
+ * Load every rule visible to this session, split into UNCONDITIONAL (always present) and
+ * CONDITIONAL (announced on-touch, `conditionalRuleAttachmentProducer` below).
+ */
+export declare function loadRules(input: LoadRulesInput): {
+    unconditional: LoadedRule[];
+    conditional: LoadedRule[];
+};
+/**
+ * Whether `filePath` matches one of `rule`'s `paths:` globs. `false` for an unconditional rule
+ * (nothing to match). `originalCwd` is the USER-tier base; a PROJECT-tier rule ignores it and uses
+ * its own fixed `projectBase` instead (see `LoadedRule.projectBase`'s header).
+ */
+export declare function ruleMatches(rule: LoadedRule, filePath: string, originalCwd: string): boolean;
+export interface ConditionalRuleAttachment extends AttachmentPayload {
+    type: "conditional_rule";
+    /** `LoadedRule.path` -- the dedupe key the "announced" fold reads back. */
+    path: string;
+    content: string;
+}
+/** Every conditional rule already announced in this history, keyed by `LoadedRule.path` -- the identical persisted-fold shape `dateChangeAnnounced`/`skillListingResumeSeed` already use. */
+export declare function announcedRulePaths(messages: readonly ProviderMessage[]): Set<string>;
+/**
+ * The conditional-rule attachment producer: scans the engine's own history for every Read/Edit/Write
+ * `file_path` an assistant turn has issued, and for each conditional rule not yet announced
+ * (`announcedRulePaths`), emits it the first time one of those paths matches. Once emitted, the
+ * PERSISTED attachment is what stops a second emission -- the fold reads it back exactly like every
+ * other attachment type does, so this producer itself carries no state across calls.
+ */
+export declare function conditionalRuleAttachmentProducer(rules: readonly LoadedRule[], opts: {
+    originalCwd: string;
+}): AttachmentProducer;

package/dist/context/seam.d.ts

@@ -0,0 +1,136 @@
+import type { RuntimeConfig } from "@yanlinglabs/winter-agent-sdk";
+import type { ContextEntry } from "./request-layout.js";
+export type SkillListing = Array<{
+    name: string;
+    description: string;
+    source: "project" | "user" | "plugin" | "builtin" | "self";
+}>;
+/**
+ * The configured output style's NAME -- `RuntimeConfig.outputStyle` / `Settings.outputStyle`, e.g.
+ * `"default"`.
+ *
+ * DIVERGENCE FROM THE BRIEF'S SPELLING, disclosed: the task-3 brief writes `outputStyle?: OutputStyle`
+ * without defining `OutputStyle`, and the obvious richer reading (a resolved `{name, body}` object)
+ * would put style RESOLUTION in the engine. It belongs to Lane C -- project-tier output styles
+ * discovery plus Winter's built-ins is that lane's own deliverable (task-6 brief), and the engine has
+ * no business reading those files. So the seam carries the name and Lane C resolves the body, and the
+ * brief's type name is kept so a lane brief citing it still lands somewhere.
+ */
+export type OutputStyle = string;
+/**
+ * Everything the assembler is allowed to depend on. Deliberately a PLAIN DATA snapshot: no
+ * filesystem handles, no live getters, nothing session-mutable. Two consequences the lanes rely on --
+ * an assembler is trivially testable from a literal, and the engine can compute this once per
+ * envelope and reuse it for every provider call in that turn without re-reading the world mid-turn.
+ *
+ * `env`/`platform`/`osVersion`/`shell`/`model` feed the `# Environment` section; `date` feeds the
+ * userContext `currentDate` entry (SDK 0.0.16). Whether the environment and auto-memory sections land
+ * in `system` or move into the index-0 userContext is `excludeDynamicSections`' job, which lives inside
+ * `config.systemPrompt`'s preset arm, not here.
+ */
+export interface SystemPromptInput {
+    config: RuntimeConfig;
+    cwd: string;
+    env: Record<string, string | undefined>;
+    platform: string;
+    osVersion: string;
+    shell: string;
+    /** The session's LOCAL calendar date, `YYYY-MM-DD` (claude's `currentDate`). */
+    date: string;
+    /** SDK 0.0.16: the model id this session generates with, for the `# Environment` model line. */
+    model?: string;
+    /** SDK 0.0.16: the model's display name, when the host's catalog knows one. */
+    modelDisplayName?: string;
+    memoryDir?: string;
+    outputStyle?: OutputStyle;
+    planMode: boolean;
+    hostPlanBody?: string;
+    /**
+     * DISCLOSED WINTER FIELD, not in the brief's list: the child persona a subagent runs with
+     * (`AgentDefinition.prompt` composed over any inherited base -- subagents/child-engine.ts computes
+     * it). R5-3 retires P4-J's first-turn concatenation of that text into the message history and
+     * routes it "through `system`" instead; this is the field it travels on.
+     *
+     * An assembler that ignores it silently drops a child's persona, so Lane C MUST compose it. The
+     * engine's own no-assembler fallback uses it VERBATIM as the whole system prompt, which is
+     * consistent with R5-16: the engine still authors no text of its own, it only forwards the
+     * caller's.
+     */
+    agentPrompt?: string;
+    /**
+     * Spawn-surface parity (research §A1's `Explore`/`Plan` field table: "`omitClaudeMd: true`;
+     * context also drops gitStatus", mirrored on `RuntimeAgentDefinition.omitProjectContext`). When
+     * true, the index-0 userContext carries NO `claudeMd` entry at all (claude's `omitClaudeMd` drops the
+     * whole value -- the auto-memory index is one of its entries, so it goes too) and the systemContext
+     * `gitStatus` is not produced (`systemContextPlacement: "none"`). Everything else -- the date, the
+     * environment and auto-memory sections, the listings -- is unaffected.
+     */
+    omitProjectContext?: boolean;
+}
+/**
+ * What the assembler produces.
+ *
+ * `system` goes on `ProviderRequest.system` (with the systemContext appended by the engine).
+ *
+ * SDK 0.0.16 (P16-5): NOTHING IS ATTACHED TO THE TURN'S USER MESSAGE ANY MORE. The instructions
+ * files and the memory index are the index-0 userContext (`SystemPromptAssembler.userContext`,
+ * memoized per session by the engine); the listings are persisted attachments
+ * (context/attachments.ts). `userContextBlocks` is gone.
+ *
+ * `presetVersion` is the version stamp of whichever authored prompt produced `system`, for
+ * conformance/diagnostics -- absent exactly when WINTER AUTHORED NOTHING (the caller-supplied
+ * `string` and `string[]` arms), stamped for `undefined` (`winter_minimal@<n>`) and the preset arm.
+ */
+export interface AssembledPrompt {
+    system: string;
+    /**
+     * SDK 0.0.16: `system` before it was joined -- the static (cacheable) half, the dynamic half, and
+     * whether the region has a dynamic boundary at all. The engine turns these into claude's cache
+     * blocks (`buildSystemBlocks`). Absent (a test double) = `system` is one uncached-scope block and the
+     * request carries no `systemBlocks`.
+     */
+    systemParts?: {
+        staticParts: string[];
+        dynamicParts: string[];
+        hasBoundary: boolean;
+    };
+    /**
+     * SDK 0.0.16: where the engine puts the systemContext `gitStatus` snapshot -- `system` (the last
+     * system part, the default layout), `userContext` (the FIRST index-0 entry, under
+     * `excludeDynamicSections`), or `none` (a caller-supplied prompt, an `omitProjectContext` agent,
+     * the kill switch, `includeGitInstructions: false`). Absent = `none`.
+     */
+    systemContextPlacement?: "system" | "userContext" | "none";
+    presetVersion?: string;
+    /**
+     * Phase 5 Task 8 (rider 22, RULING P5-G): TRUE when a PROJECT-tier output style asked to replace
+     * Winter's authored prompt (`keep-coding-instructions: false`) and the assembler downgraded it to
+     * an append because the host has not declared workspace trust. ABSENT (never `false`) otherwise.
+     */
+    replacementDowngraded?: boolean;
+}
+export interface SystemPromptAssembler {
+    assemble(input: SystemPromptInput): AssembledPrompt;
+    /**
+     * SDK 0.0.16 (P16-5): the session's userContext entries, in claude's key order -- `claudeMd`, then
+     * `currentDate` (then, under `excludeDynamicSections`, `Environment` and `auto memory`). The ENGINE
+     * memoizes the result per session and clears it on compaction, so this reads the filesystem once
+     * per session context rather than once per turn. Absent = no index-0 message.
+     */
+    userContext?(input: SystemPromptInput): ContextEntry[];
+}
+/**
+ * The spine's own test double. NOT a minimal prompt and never a stand-in for one (R5-16): it echoes
+ * its inputs in a mechanically checkable shape so an engine test can prove the assembled result
+ * reached the LIVE request, and so a lane can develop against a producer that exists.
+ *
+ * Every part is optional-in, deterministic, and free of authored prose.
+ */
+export declare function fakeSystemPromptAssembler(opts?: {
+    system?: string;
+    /** SDK 0.0.16: the userContext entries the fake answers (absent = none, so no index-0 message). */
+    userContext?: ContextEntry[];
+    presetVersion?: string;
+    /** Records every input the engine handed over, in call order -- the "was it called per turn, with what?" assertion. */
+    calls?: SystemPromptInput[];
+}): SystemPromptAssembler;

package/dist/context/tool-epoch.d.ts

@@ -0,0 +1,118 @@
+import type { ProviderMessage, ProviderToolSpec } from "../engine.js";
+import type { ToolChangeSet } from "@yanlinglabs/winter-provider-runtime";
+import type { AttachmentPayload } from "./attachments.js";
+/**
+ * Which vendor form this epoch's changes take. Chosen per model from its catalog evidence:
+ *   - `anthropic-inline`: by value and by reference (`inlineToolDefinitions`, Claude API only);
+ *   - `anthropic-reference`: by reference only (`midConversationToolChanges`);
+ *   - `openai`: `additional_tools` and/or `allowed_tools` (`additionalToolsItem` / `allowedToolsChoice`).
+ */
+export type ToolChangeMechanism = "anthropic-reference" | "anthropic-inline" | "openai";
+export declare const TOOL_EPOCH_ATTACHMENT = "tool_epoch";
+export declare const TOOL_CHANGES_ATTACHMENT = "tool_changes";
+/** The epoch's frozen `tools` array, verbatim, and the model and mechanism it was frozen for. */
+export interface ToolEpochAttachment extends AttachmentPayload {
+    type: "tool_epoch";
+    mechanism: ToolChangeMechanism;
+    /** The catalog key of the model the epoch belongs to (`null` for a session with no identity). */
+    modelKey: string | null;
+    tools: ProviderToolSpec[];
+}
+/**
+ * One change point. `declare` is appended to `tools` from here on (Anthropic's deferred declarations:
+ * a tool must be declared before a reference can name it); `remove` and `add` are what the model reads
+ * at this position.
+ */
+export interface ToolChangesAttachment extends AttachmentPayload {
+    type: "tool_changes";
+    mechanism: ToolChangeMechanism;
+    /**
+     * WS-23 (reasoning-state): the model whose epoch this change extends. Several models' epochs can now
+     * sit in one history (a switch no longer retires the earlier model's), so each change names its own.
+     * Absent on an entry a dev build wrote into the transcript: it belongs to the epoch before it.
+     */
+    modelKey?: string | null;
+    declare: ProviderToolSpec[];
+    remove: string[];
+    add: ToolChangeSet["add"];
+}
+export declare function isToolEpochMessage(message: ProviderMessage): boolean;
+export declare function isToolChangesMessage(message: ProviderMessage): boolean;
+/** Either bookkeeping attachment -- neither is ever sent as text. */
+export declare function isToolBookkeeping(message: ProviderMessage): boolean;
+/** The identity of one definition as the model reads it: name, description, schema -- never Winter's own flags. */
+export declare function toolDefinitionKey(spec: {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}): string;
+/**
+ * The history's newest epoch for `mechanism` on `modelKey` -- that MODEL's own, wherever it sits.
+ *
+ * WS-23 (reasoning-state): a later epoch of ANOTHER model no longer retires this one. The tool list is a
+ * cache quirk of one model, so each model keeps its own epoch in the history and reads only its own:
+ * after Claude -> GPT -> Claude, Claude's epoch (and the cached prefix it heads) is still there to
+ * resume. Whether it SHOULD be resumed -- the cache may have expired while the other model ran -- is the
+ * engine's call (`planToolsForRequest`, the TTL rule); this only finds it.
+ */
+export declare function activeToolEpoch(history: readonly ProviderMessage[], mechanism: ToolChangeMechanism, modelKey: string | undefined): {
+    index: number;
+    epoch: ToolEpochAttachment;
+} | undefined;
+/**
+ * The `tool_changes` entries that belong to the epoch at `epochIndex`, in order: after it, on its
+ * mechanism, and of its MODEL (WS-23 -- another model's changes in between are that model's). A change
+ * with no `modelKey` (a dev-build transcript entry) belongs to whichever epoch precedes it.
+ */
+export declare function epochChangeMessages(history: readonly ProviderMessage[], epochIndex: number, mechanism: ToolChangeMechanism): ProviderMessage[];
+/** What the model can see at the tail of an epoch: the declared `tools` array, and the tools it may call. */
+export interface ToolState {
+    /** The request's `tools` array: the frozen list, then every `declare` in order. Never sorted again. */
+    declared: ProviderToolSpec[];
+    /** Name -> the definition the model currently has for it. */
+    available: Map<string, ProviderToolSpec>;
+}
+/**
+ * Folds an epoch and its change entries into the state at the tail. `referenced` are the deferred names
+ * a ToolSearch result surfaced (`tool_result.loadedTools`): on Anthropic those are callable through the
+ * `tool_reference` blocks the adapter writes into the result, so they count as available.
+ */
+export declare function foldToolState(epoch: ToolEpochAttachment, changes: readonly ProviderMessage[], referenced?: ReadonlySet<string>): ToolState;
+/** The frozen `tools` array for a NEW epoch. OpenAI's client tool search never declares a deferred tool (it rides the search output). */
+export declare function epochToolsFor(live: readonly ProviderToolSpec[], mechanism: ToolChangeMechanism): ProviderToolSpec[];
+/** What the mechanism can express, from the row's evidence. */
+export interface ToolChangeCaps {
+    /** OpenAI: an `additional_tools` item may add or redefine a tool. */
+    additionalTools?: boolean;
+    /** OpenAI: `tool_choice: allowed_tools` may restrict the callable set. */
+    allowedTools?: boolean;
+}
+export type ToolDiff = {
+    kind: "same";
+    allowedTools?: string[];
+} | {
+    kind: "change";
+    change: Pick<ToolChangesAttachment, "declare" | "remove" | "add">;
+    allowedTools?: string[];
+}
+/** The mechanism cannot express this change: start a new epoch (today's full rebuild of `tools`, once). */
+ | {
+    kind: "new-epoch";
+    reason: string;
+};
+/**
+ * The live tool list against the folded state: what to append, or that the epoch cannot express it.
+ *
+ * `live` is the engine's own per-request list (sorted by name; on a deferred-loading row, deferred tools
+ * carry `deferLoading`, which means "declared, not shown"). Deterministic: removals and additions are in
+ * name order, declarations in `live` order.
+ */
+export declare function diffToolState(live: readonly ProviderToolSpec[], state: ToolState, mechanism: ToolChangeMechanism, caps?: ToolChangeCaps): ToolDiff;
+/** The wire form of one `tool_changes` entry: an empty-content `system` message, or `undefined` when it says nothing. */
+export declare function toolChangesWireMessage(message: ProviderMessage): ProviderMessage | undefined;
+/**
+ * The deferred tools a `tool_changes` entry of the current epoch surfaced by reference (see
+ * `referencedToolNames`). WS-23: with `modelKey`, the current epoch is THAT model's newest (and only its
+ * own changes count); without, the history's last epoch of any model -- the pre-WS-23 reading.
+ */
+export declare function toolChangeReferences(history: readonly ProviderMessage[], modelKey?: string | null): string[];

package/dist/context/winter-code-preset.d.ts

@@ -0,0 +1,39 @@
+import { type BrandProfile, type SystemPromptPreset } from "@yanlinglabs/winter-agent-sdk";
+/**
+ * The categories WS-11 §6.2 requires, in the order the document lists them. Each is a `## `
+ * heading in the preset, which is what makes coverage checkable by a test rather than by a reader.
+ */
+export declare const WINTER_CODE_PRESET_CATEGORIES: readonly string[];
+/**
+ * Bump on any edit to `presets/winter-code.md`. WS-11 §6.2 requires the preset to be versioned so a
+ * conformance run can say WHICH authored preset it compared, and so a behaviour change is
+ * attributable to a prompt revision rather than to a model.
+ */
+export declare const WINTER_CODE_PRESET_VERSION: string;
+/** The authored preset text. Trailing whitespace trimmed once, here, so no caller has to. */
+export declare const WINTER_CODE_PRESET: string;
+/**
+ * Both accepted spellings of the preset for a given brand. `claude_code` is the Claude-mirroring
+ * compatibility alias (WS-01 §5, never rebranded); `brand.presetName` is the native one (WS-01 §6).
+ */
+export declare function winterCodePresetNames(brand?: Pick<BrandProfile, "presetName">): readonly string[];
+/** The default profile's pair, for every caller that has not threaded a brand. */
+export declare const WINTER_CODE_PRESET_NAMES: readonly string[];
+export declare function isWinterCodePreset(preset: string, brand?: Pick<BrandProfile, "presetName">): boolean;
+/**
+ * The preset arm's system text: the preset, then `append`.
+ *
+ * `append` ADDS; it never replaces any part of the preset (WS-11 §6.2). A whitespace-only append is
+ * treated as absent so a host that always sets the field from an optional config value does not get
+ * a trailing blank section.
+ */
+export declare function resolvePresetSystemPrompt(preset: SystemPromptPreset): string;
+/**
+ * Removes ONLY the coding-instructions section from an authored prompt string, collapsing the
+ * resulting blank-line run back down to one blank line. A SAFE NO-OP when the start heading is
+ * absent (e.g. `MINIMAL_PROMPT`, which has no such section at all -- fix round 4 disclosed this as
+ * an intentional behaviour change, see `assembler.test.ts`) or when the end heading cannot be found
+ * after it (a malformed/future preset shape): returns `prompt` unchanged rather than guessing at or
+ * truncating past a boundary that turned out not to be there.
+ */
+export declare function dropCodingInstructionsSection(prompt: string): string;