@yanlinglabs/winter-agent-runtime 0.0.27

package/dist/store/provider-state.d.ts

@@ -0,0 +1,188 @@
+import type { MessageOrigin, ProviderNativeState } from "@yanlinglabs/winter-provider-runtime";
+import { PROVIDER_STATE_FILE_SUFFIX } from "@yanlinglabs/winter-agent-sdk";
+/** The `SessionStoreEntry.type` discriminant every record carries. One string, one place. */
+export declare const PROVIDER_STATE_ENTRY_TYPE: "winter_provider_state";
+/**
+ * R6-7a: the subpath a NON-filesystem `SessionStore` receives these records under.
+ *
+ * Resume `load()`s this key DIRECTLY and never relies on `listSubkeys` -- that method is optional on
+ * the pinned `SessionStore` (`sdk.d.ts:5353-5356`) and, when a host's adapter omits it, "resume only
+ * materializes the main transcript". A provider-state subpath discovered by enumeration would be
+ * written and then never found, silently.
+ */
+export declare const PROVIDER_STATE_SUBPATH: "provider-state";
+/**
+ * The filename suffix of the neighbour file, RE-EXPORTED from the sdk store.
+ *
+ * ONE DECLARATION (re-review round 2). The sdk's `delete()` must name this file to remove it and
+ * cannot import the runtime (WS-02 §3), so the string is declared there and imported here -- the same
+ * direction every other shared store constant takes. This package still owns the record SEMANTICS;
+ * only the literal moved. The P4-M read deny and the sidecar path builder both read it from here, so
+ * they cannot drift from what the deletion transaction actually removes.
+ */
+export { PROVIDER_STATE_FILE_SUFFIX };
+export type ProviderStateKind = "origin" | "native-state" | "summary" | "handoff" | "reasoning-blocks" | "effort" | "tool-epoch" | "tool-changes" | "decoration";
+/**
+ * One sidecar record. The envelope (`type`/`uuid`/`timestamp`) plus R6-7's own payload fields.
+ *
+ * `anchorUuid` names the ASSISTANT ENTRY this record belongs to -- the uuid the engine pre-allocated
+ * and passed through `recordAssistantEntry(content, { uuid })`. `itemIndex` orders multiple records
+ * sharing one anchor. `payload` is opaque BY TYPE: `unknown`, so nothing is tempted to inspect it.
+ */
+export interface ProviderStateRecord {
+    [k: string]: unknown;
+    type: typeof PROVIDER_STATE_ENTRY_TYPE;
+    uuid: string;
+    timestamp: string;
+    sessionId: string;
+    anchorUuid: string;
+    provider: string;
+    model: string;
+    family: string;
+    continuationDomain?: string;
+    itemIndex: number;
+    kind: ProviderStateKind;
+    payload: unknown;
+}
+/**
+ * What a CALLER supplies. The three envelope fields are stamped here when omitted, so a producer
+ * cannot forget the `type` discriminant or accidentally reuse the anchor as the record uuid -- the
+ * two mistakes item (h) identifies as fatal to an external store. A fully-formed `ProviderStateRecord`
+ * also satisfies this type, so a caller that has one (a replay, a test fixture) passes it unchanged.
+ */
+export interface ProviderStateRecordInput {
+    type?: typeof PROVIDER_STATE_ENTRY_TYPE;
+    uuid?: string;
+    timestamp?: string;
+    sessionId: string;
+    anchorUuid: string;
+    provider: string;
+    model: string;
+    family: string;
+    continuationDomain?: string;
+    itemIndex: number;
+    kind: ProviderStateKind;
+    payload: unknown;
+}
+/** Stamps the envelope. Separated from the append so the external-store door (which never touches a file) produces byte-identical records. */
+export declare function toProviderStateRecord(input: ProviderStateRecordInput): ProviderStateRecord;
+/**
+ * `<dir>/<sessionId>.provider-state.jsonl` -- the neighbour of `<dir>/<sessionId>.jsonl`.
+ *
+ * DERIVED FROM THE TRANSCRIPT PATH rather than rebuilt from (winterHome, projectKey, sessionId),
+ * which is what makes the CHILD case fall out for free: a child transcript at
+ * `<sessionId>/subagents/agent-<id>.jsonl` yields `<sessionId>/subagents/agent-<id>.provider-state.jsonl`
+ * with no second path-shaping rule to keep in step. R6-7 words the child path as
+ * `<sessionId>/subagents/<agentId>.provider-state.jsonl`; the real child transcript basename is
+ * `agent-<agentId>` (dialect.ts's `childTranscriptSubpath`), and matching the actual neighbour is what
+ * "beside the child transcript" means -- recorded as a deliberate reading of the brief, not a drift.
+ */
+export declare function providerStateSidecarPath(transcriptPath: string): string;
+/**
+ * Appends ONE record: 0600, `O_APPEND`, one `fsync` per record.
+ *
+ * `fsync` per record and not per batch, deliberately: the whole point of write-ahead ordering is that
+ * the record is DURABLE before its entry is appended. A batched flush would make the ordering true in
+ * memory and false on disk, which is the only place it matters.
+ *
+ * Returns the stamped record (a deviation from the brief's `void`, recorded): the caller needs the
+ * minted `uuid` to write the identical envelope through an external store, and a producer that had to
+ * re-derive it would be a second minting site.
+ */
+export declare function appendProviderState(path: string, input: ProviderStateRecordInput): ProviderStateRecord;
+/**
+ * The most record bytes one read KEEPS. A sidecar is a few small records per assistant entry, so 64 MiB
+ * is orders of magnitude above any ordinary session; the bound exists because this file is read on
+ * EVERY resume and a file grown without limit (a very long session, a corrupt or attacker-grown file)
+ * must not be read into memory without limit.
+ *
+ * WS-23 (reasoning-state, defect c): a bound on what is KEPT, not a refusal of the file. The read used
+ * to throw past 64 MiB, and every caller turned the throw into an EMPTY chain -- one byte over the
+ * limit and a session lost the native state of every turn it had, including the ones it was about to
+ * continue from. Since the move of Anthropic thinking into the sidecar that is a session's whole
+ * reasoning. Now the file is streamed and, once the kept records pass the bound, the OLDEST are let go:
+ * the turns nearest the current work keep their state, and the oldest degrade to summary level (which
+ * `buildContinuationChain` already handles, record by record).
+ */
+export declare const PROVIDER_STATE_MAX_READ_BYTES: number;
+/** One line longer than this is not a record Winter wrote (a single turn's state is far smaller); it is skipped unread. */
+export declare const PROVIDER_STATE_MAX_LINE_BYTES: number;
+/**
+ * Reads a sidecar with BOUNDED REPAIR: a truncated final line is dropped and every earlier record is
+ * kept.
+ *
+ * That is the crash the write-ahead ordering makes likely -- the process died mid-`writeSync` -- and
+ * refusing the whole file for it would discard a session's entire continuation chain over one partial
+ * line. A malformed line ANYWHERE (not just the last) is skipped for the same reason; the chain
+ * degrades record by record rather than all at once, and `buildContinuationChain` already treats a
+ * missing record as "degrade this message to summary-level".
+ *
+ * BOUNDED MEMORY (WS-23, review r1 I-4): streamed in 1 MiB chunks, a line past
+ * `PROVIDER_STATE_MAX_LINE_BYTES` is skipped without being buffered, and the records RETAINED never exceed
+ * `PROVIDER_STATE_MAX_READ_BYTES` (plus one compaction step's slack) -- the oldest are released AS THE
+ * READ GOES, and the released entries are cut out of the working list every time they pass half of it, so
+ * memory stays proportional to the bound, never to the file. `limits` exists for tests (`stats` reports
+ * the peak number of entries the list ever held).
+ *
+ * A missing file is an EMPTY chain, never a throw: "no sidecar" and "sidecar emptied" are
+ * indistinguishable by design in the pinned store contract (`load()` may return `null` for both,
+ * `sdk.d.ts:5302-5314`), so the filesystem path answers the same way its store-backed twin must.
+ */
+export declare function readProviderState(path: string, limits?: {
+    maxKeptBytes?: number;
+    maxLineBytes?: number;
+    stats?: {
+        peakRetained: number;
+    };
+}): ProviderStateRecord[];
+/**
+ * One line -> one record, or `undefined`.
+ *
+ * VALIDATES STRUCTURALLY rather than casting: these bytes come off disk (or out of a host's own
+ * `SessionStore`), and a cast would let a malformed `origin` payload surface as an incomprehensible
+ * failure inside an adapter three layers away. Exported because the external-store door validates the
+ * identical way -- one parser, two transports.
+ */
+export declare function parseProviderStateLine(line: string): ProviderStateRecord | undefined;
+export declare function coerceProviderStateRecord(value: unknown): ProviderStateRecord | undefined;
+/** What one assistant entry's records fold into. `origin` is mandatory in a healthy chain; its ABSENCE is what degrades that message to summary-level. */
+export interface ContinuationLink {
+    origin?: MessageOrigin;
+    nativeState?: ProviderNativeState;
+    summary?: string;
+    material?: "exposed";
+    complete?: boolean;
+    /** WS-23: when the `origin` record was written -- the time the reply landed, which the tool epoch's cache-TTL rule reads. */
+    recordedAt?: string;
+    /** WS-23 (layer 2): the entry's effort annotations, from an `effort` record. */
+    effort?: {
+        effort?: string;
+        perTurnEffort?: string;
+    };
+    /** Review r1, M-1: per TARGET model key, the decoration that target was sent for this entry (`null`: none). */
+    decorations?: Record<string, {
+        text: string;
+        door: "tag" | "thinking-channel";
+    } | null>;
+    /** WS-23 (layer 2): the tool-epoch bookkeeping that PRECEDED this entry, in write order (attachment payloads). */
+    bookkeeping?: Array<{
+        type: string;
+        [key: string]: unknown;
+    }>;
+}
+/**
+ * Folds the records into a per-entry chain, keyed by `anchorUuid`.
+ *
+ * A RECORD WHOSE ANCHOR IS MISSING IS IGNORED, not an error: the write-ahead ordering makes exactly
+ * that pair the likely crash (the record was fsync'd, the process died before its entry appended), so
+ * it is garbage-collectable state rather than corruption. The OTHER crash pair -- an entry with no
+ * record -- is not visible here at all: it shows up as an anchor the returned map has no key for, and
+ * the caller degrades that message to summary-level and warns. Both halves are asserted in
+ * provider-state.test.ts's crash-pair fixture.
+ *
+ * Records are folded in ARRAY ORDER (which is append order), so a later record of the same kind for
+ * the same anchor wins -- a re-recorded `native-state` supersedes the one before it.
+ */
+export declare function buildContinuationChain(records: readonly ProviderStateRecord[], entryUuids: ReadonlySet<string>): Map<string, ContinuationLink>;
+/** The ledger's pinned alias: every lane types its renderer against `ReturnType<typeof buildContinuationChain>`, so the chain's shape has exactly one definition. */
+export type ContinuationChain = ReturnType<typeof buildContinuationChain>;

package/dist/store/resume.d.ts

@@ -0,0 +1,92 @@
+import type { ProviderMessage } from "../engine.js";
+import type { SessionStore, SessionStoreEntry } from "@yanlinglabs/winter-agent-sdk";
+export declare class ResumeTargetError extends Error {
+    readonly reason: "not_found" | "ambiguous" | "locked";
+    constructor(reason: "not_found" | "ambiguous" | "locked", message: string);
+}
+export declare class ResumeTruncationError extends Error {
+    constructor(message: string);
+}
+/** `continue: true` — the newest session in exactly one directory (WS-05 §7: no cross-project fallback). */
+export declare function findContinueTarget(store: SessionStore, cwdKey: string): Promise<string | null>;
+/**
+ * `resume: <uuid>` — current project first (an unconditional win, never subject to the ambiguity
+ * check below, even if the same id ALSO happens to exist elsewhere); then every other project,
+ * resolving only on a unique foreign match.
+ *
+ * Deferred scope (documented, not silently dropped): WS-05 §7 also says to search "the current
+ * project + its git worktrees" before falling through to every other project. P1 has no
+ * worktree-aware transcriptProjectKey (compatibilityKeys' worktree-awareness is memoryProjectKey
+ * only, WS-05 §3.2) and the outer task brief's own restatement of this rule omits worktrees
+ * entirely — a worktree session resolves via the ordinary "every other project" fallback today
+ * (correct, just not distinguished from any other foreign project), until a later task adds
+ * worktree identity to the search's first phase.
+ */
+export declare function findResumeTarget(store: SessionStore, opts: {
+    sessionId: string;
+    cwdKey: string;
+}): Promise<{
+    projectKey: string;
+}>;
+export interface DialectEntry {
+    type: string;
+    uuid: string;
+    parentUuid: string | null;
+    message?: {
+        role: string;
+        content: unknown;
+        model?: string;
+    };
+    compact_metadata?: unknown;
+    subtype?: string;
+    compactMetadata?: unknown;
+    logicalParentUuid?: string;
+    isCompactSummary?: boolean;
+    isApiErrorMessage?: boolean;
+    attachment?: {
+        type: string;
+        [key: string]: unknown;
+    };
+    effort?: string;
+    perTurnEffort?: string;
+}
+/** Narrows a loaded SessionStoreEntry[] to the entries that actually carry a chain identity (WS-05
+ * §5.2's chain guarantee applies to entries with a uuid; mirrors dialect.ts's own validateChain
+ * narrowing) — an entry with no uuid at all is simply not part of the resumable chain. */
+export declare function toDialectEntries(raw: SessionStoreEntry[]): DialectEntry[];
+/**
+ * `chain` (root-first) with each parallel batch's off-chain call entries and results spliced in
+ * right after the batch's last chain entry. `pool` is where they are looked for (the loaded file, or
+ * what of it a truncation keeps in play), in file (append) order. Returns a copy of `chain` when
+ * nothing was recovered.
+ */
+export declare function recoverParallelToolResults(chain: readonly DialectEntry[], pool: readonly DialectEntry[]): DialectEntry[];
+/**
+ * `resumeSessionAt` — keep only `atUuid`'s own ancestry; `resumeDropsTurn` confirms the caller
+ * intends to discard whatever DESCENDS from it. This NEVER mutates or deletes stored entries — the
+ * store is append-only (WS-05 §6): whatever is excluded stays on disk untouched, and continuing
+ * from `atUuid` grows a new branch alongside it.
+ *
+ * Ruling P1-R (fix-round 1 — settles this function's originally-provisional interpretation; see
+ * resume.test.ts for the two scenarios that pin it): both "kept" and "dropped" are graph-defined,
+ * never positional.
+ *   - kept = atUuid's own ancestry (`ancestryChain` above), root to atUuid — independent of where
+ *     atUuid sits in file order, and independent of anything else in the file.
+ *   - dropped = every entry that DESCENDS from atUuid (its ancestry passes through atUuid),
+ *     EXCLUDING atUuid itself. "Every dropped entry descends from the target" (the brief's
+ *     original phrasing) IS the definition of "dropped" here — not a validation performed after
+ *     computing "dropped" some other (positional) way.
+ *   - an entry that is NEITHER an ancestor NOR a descendant of atUuid — an off-lineage sibling
+ *     branch, e.g. one abandoned by an earlier, unrelated resumeSessionAt — is simply not on the
+ *     lineage this operation concerns: it needs NO confirmation and triggers NO error regardless of
+ *     dropsTurn, because resuming at atUuid neither keeps nor discards it; it was never part of
+ *     this operation to begin with. Concretely: resuming at an already-abandoned tip (nothing
+ *     downstream of it survives to be dropped) succeeds with `dropsTurn:false`.
+ *   - dropsTurn:false + real descendants exist -> typed error (silently discarding real turn
+ *     content without acknowledgment is refused); dropsTurn:true -> allowed.
+ */
+export declare function truncateAt(entries: DialectEntry[], opts: {
+    atUuid: string;
+    dropsTurn: boolean;
+}): DialectEntry[];
+export declare function rebuildProviderMessages(entries: DialectEntry[]): ProviderMessage[];

package/dist/structured/ajv-seam.d.ts

@@ -0,0 +1,7 @@
+import type { StructuredOutputSeam } from "./seam.js";
+/**
+ * One seam per session (or per workflow host). The ajv instances and the compiled-validator cache
+ * live inside the closure, so two concurrent sessions never share compile state and a finished one
+ * releases it.
+ */
+export declare function createStructuredOutputSeam(): StructuredOutputSeam;

package/dist/structured/descriptor.d.ts

@@ -0,0 +1,9 @@
+import type { ToolDescriptor } from "../tools/registry.js";
+import { type JsonSchema } from "./seam.js";
+/**
+ * Winter's own description of the tool. It is what the model reads to know HOW to return, so it says
+ * that calling it ends the turn -- the engine's turn-ending rule is otherwise invisible to the model,
+ * which would keep working after it had already answered.
+ */
+export declare const STRUCTURED_OUTPUT_TOOL_DESCRIPTION: string;
+export declare function buildStructuredOutputDescriptor(schema: JsonSchema): ToolDescriptor;

package/dist/structured/seam.d.ts

@@ -0,0 +1,51 @@
+import type { JSONSchema, ToolDescriptor } from "../tools/registry.js";
+/** The caller's `outputFormat.schema`. Aliased to the registry's own JSONSchema so the descriptor's `inputSchema` can be assigned the value VERBATIM, with no re-shaping step in between. */
+export type JsonSchema = JSONSchema;
+/** The tool name, one constant. Never hand-written at a call site -- an advertised-set assertion and a dispatch check that disagreed by a letter would be invisible. */
+export declare const STRUCTURED_OUTPUT_TOOL_NAME = "StructuredOutput";
+/**
+ * The ONLY names a host-generated registration may claim (fix round 1, M1). Re-exported here for
+ * Lane K's convenience; it is DEFINED in `tools/registry.ts`, which is what enforces it -- the
+ * registry must not depend on this module, and a second copy of the set is exactly the drift the
+ * allowlist exists to prevent.
+ */
+export { HOST_GENERATABLE_TOOL_NAMES } from "../tools/registry.js";
+/**
+ * The default number of ATTEMPTS, not retries. Capture (6) is explicit and was run both ways: with
+ * the env unset the pinned runtime produced FIVE validation-failure tool results and terminated with
+ * "after 5 attempts"; with `MAX_STRUCTURED_OUTPUT_RETRIES=2` it produced TWO. Reading the name as
+ * "retries after the first attempt" would give six calls where the pin gives five.
+ */
+export declare const DEFAULT_MAX_STRUCTURED_OUTPUT_ATTEMPTS = 5;
+/** The unbranded env spelling, verbatim (Global Constraints: this family is NOT Winter-branded). */
+export declare const MAX_STRUCTURED_OUTPUT_RETRIES_ENV = "MAX_STRUCTURED_OUTPUT_RETRIES";
+/** Resolves the attempt budget from an environment snapshot. A non-numeric or non-positive value is ignored (the default stands) rather than producing a budget no run could ever satisfy. */
+export declare function resolveMaxStructuredOutputAttempts(env: Record<string, string | undefined>): number;
+export interface StructuredOutputSeam {
+    /**
+     * Builds the host-generated descriptor. The implementation MUST put `schema` on `inputSchema`
+     * unchanged -- not merged into a wrapper, not normalized, not re-serialized. The engine registers
+     * whatever comes back and advertises it only while `outputFormat` is set.
+     */
+    buildDescriptor(schema: JsonSchema): ToolDescriptor;
+    /**
+     * Validates a model-supplied value against the caller's schema. `errors` are model-facing: capture
+     * (6) observed the pinned runtime returning text naming the JSON-Pointer path and the expected
+     * type (ajv's own rendering), which is the target shape.
+     */
+    validate(schema: JsonSchema, value: unknown): {
+        ok: true;
+        value: unknown;
+    } | {
+        ok: false;
+        errors: string[];
+    };
+}
+/**
+ * The spine's test double. Validation is deliberately CRUDE (required-key presence and a `type`
+ * check on primitives) -- it exists to drive the engine's accept/retry/exhaust branches, never to
+ * stand in for ajv. Lane K replaces it wholesale.
+ */
+export declare function fakeStructuredOutputSeam(opts?: {
+    calls?: unknown[];
+}): StructuredOutputSeam;

package/dist/structured/validator.d.ts

@@ -0,0 +1,22 @@
+import { type ErrorObject, type ValidateFunction } from "ajv";
+import type { JsonSchema } from "./seam.js";
+/** A caller schema that ajv cannot compile at all. Distinct from a validation failure -- see below. */
+export declare class StructuredSchemaError extends Error {
+}
+/**
+ * Renders ajv's errors as model-facing text. Capture (6) observed the pinned runtime returning text
+ * naming the JSON-Pointer path and the expected type -- ajv's own rendering -- which is the target
+ * shape, so this stays a thin projection of `instancePath` + `message` rather than a bespoke prose
+ * layer that would drift from it.
+ *
+ * A root-level failure is reported at `/`, never at the empty string ajv uses: `": must be object"`
+ * reads as a typo, and the pointer is the thing the model navigates by.
+ */
+export declare function formatValidationErrors(errors: ErrorObject[] | null | undefined): string[];
+/**
+ * Compiles per SCHEMA OBJECT and caches by identity. The engine hands the same `outputFormat.schema`
+ * object to `validate` on every attempt of every turn, so a per-call compile would re-parse the
+ * schema up to five times per turn for the life of the session. A `WeakMap` rather than a `Map` so a
+ * finished session's schema is collectable.
+ */
+export declare function createSchemaValidatorCache(): (schema: JsonSchema) => ValidateFunction;

package/dist/subagents/activity.d.ts

@@ -0,0 +1,13 @@
+/** `trunc(s)`: collapse whitespace runs (newlines included) to one space, trim, and keep the first 50 chars + `…` when longer. */
+export declare function truncActivity(s: string): string;
+/** `path(p)`: relative to the session cwd when inside it (no leading `..`), else `~/…` under the home dir, else absolute. */
+export declare function displayActivityPath(p: string, cwd: string, home: string | undefined): string;
+export interface ActivityContext {
+    cwd: string;
+    home?: string;
+}
+/**
+ * The activity text for one recorded tool call, or `undefined` when the tool has none (any tool not in
+ * the contract's table). A missing field takes the table's own fallback text.
+ */
+export declare function toolActivityDescription(toolName: string, rawInput: unknown, ctx: ActivityContext): string | undefined;

package/dist/subagents/availability.d.ts

@@ -0,0 +1,30 @@
+import type { SourcedAgentDefinition } from "./definitions.js";
+export interface AgentAvailabilityInputs {
+    /** R3b §4: a per-type `Agent(<type>)` DENY rule -- `findAgentDenyRule(rules, type) !== undefined`, injected so this module takes no dependency on evaluator.ts/ruleset.ts's own rule types. */
+    isDenied: (agentType: string) => boolean;
+    /** R3b §4: the running agent's (or the session's) own `tools: ["Agent(a,b)"]` restriction -- `allowedAgentTypesFromTools`'s own result. `undefined` = unrestricted. */
+    allowedAgentTypes?: readonly string[];
+    /** R3b §4 `zFn`: is EVERY tool this definition may use itself denied right now? See `isBuiltinAllToolsDenied` below for the one production implementation. */
+    isAllToolsDenied: (def: SourcedAgentDefinition) => boolean;
+}
+/**
+ * claude's `l8n`, composed: the filtered set of `subagent_type` names a session may list/resolve
+ * right now. Order-preserving over `defs`' own iteration order (a `Map`'s insertion order) -- the
+ * caller sorts if it wants a sorted list, exactly as `sessionAgentDefinitions()`'s existing
+ * consumers already do for the unfiltered set.
+ */
+export declare function availableAgentNames(defs: ReadonlyMap<string, SourcedAgentDefinition>, inputs: AgentAvailabilityInputs): string[];
+/**
+ * claude's `zFn`: a built-in with an EXPLICIT `tools` list, every one of whose (concrete) tools is
+ * itself denied right now, is unavailable -- "Agent type '<x>' is unavailable because every tool it
+ * may use is denied by the current permission settings." Winter's own Explore/Plan built-ins use
+ * `disallowedTools` (an ADDITIVE restriction over "all tools"), never an explicit `tools` list, so
+ * they are EXEMPT from this filter by construction (`def.tools === undefined` always reads false
+ * here) -- exactly R3b §4's own "built-ins with explicit tools list only."
+ *
+ * `advertised` is the session's own currently-advertised canonical tool-name set (engine.ts's
+ * `currentAdvertisedCanonicalNames`) -- the SAME ground truth the pre-existing "bare-denied" check
+ * (engine.ts, disallowedTools:["t"] -> t absent from that set) already uses, not a second,
+ * independently-derived notion of "denied."
+ */
+export declare function isBuiltinAllToolsDenied(def: Pick<SourcedAgentDefinition, "tools">, advertised: readonly string[]): boolean;

package/dist/subagents/builtin-agents.d.ts

@@ -0,0 +1,37 @@
+import { type BrandProfile, type RuntimeAgentDefinition } from "@yanlinglabs/winter-agent-sdk";
+/** The one brand slice every reader/prompt-builder in this module needs. */
+type BuiltinAgentBrand = Pick<BrandProfile, "envPrefix" | "productName">;
+export interface BuiltinAgentGates {
+    /** `<PREFIX>AGENT_SDK_DISABLE_BUILTIN_AGENTS` -- mirrors `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`. When true, EVERY built-in (gated or not) is withheld, matching claude's own non-interactive-SDK branch (research §A1: "if ... && non-interactive → []" -- Winter's whole runtime is the non-interactive SDK shape, so the qualifier is unconditional here). */
+    allBuiltinsDisabled: boolean;
+    /** `<PREFIX>DISABLE_EXPLORE_PLAN_AGENTS` -- withholds `Explore` and `Plan` together (claude withholds them together too). */
+    explorePlanDisabled: boolean;
+    /** `<PREFIX>DISABLE_AGENT_VIEW` -- withholds the `claude` catch-all built-in (claude's own `CLAUDE_CODE_DISABLE_AGENT_VIEW` / `settings.disableAgentView`). */
+    agentViewDisabled: boolean;
+    /** `<PREFIX>WEB_FETCH_AGENT` -- OPT-IN: `web-fetch` is withheld unless this is truthy (claude's own default is `false` too). */
+    webFetchAgentEnabled: boolean;
+    /** `<PREFIX>FORK_SUBAGENT` (R-S5, mirrors `CLAUDE_CODE_FORK_SUBAGENT`) -- OPT-IN: `fork` is withheld unless this is truthy. `false` and absent both mean off (Winter sessions are non-interactive, like an SDK session -- there is no "interactive default: on" branch here, unlike claude's own CLI). */
+    forkSubagentEnabled: boolean;
+}
+/**
+ * R-S5: the fork gate alone, exported separately -- `tools/descriptors/agent.ts`'s own schema/
+ * description functions (item 5) and `tools/impl/agent.ts` (lane L2b) both need "is fork on" without
+ * pulling in the rest of `BuiltinAgentGates` or re-deriving the env read.
+ */
+export declare function resolveForkSubagentEnabled(env?: Record<string, string | undefined>, brand?: BuiltinAgentBrand): boolean;
+export declare function resolveBuiltinAgentGates(env?: Record<string, string | undefined>, brand?: BuiltinAgentBrand): BuiltinAgentGates;
+export declare const BUILTIN_AGENT_NAMES: readonly ["general-purpose", "Explore", "Plan", "claude", "web-fetch", "fork"];
+export type BuiltinAgentName = (typeof BUILTIN_AGENT_NAMES)[number];
+/**
+ * The resolved built-in set for THIS session, gated per `BuiltinAgentGates` (R-S6) and the fork gate
+ * (R-S5). Keys are IDENTICAL to claude's own (R-S2) so a model's own prior training transfers, and a
+ * same-named user/project/plugin/programmatic definition overrides one of these entries at MERGE time
+ * (`definitions.ts`'s own precedence chain, lowest tier -- this function does not know about, and
+ * never needs to know about, the other three sources).
+ */
+export declare function resolveBuiltinAgents(opts?: {
+    env?: Record<string, string | undefined>;
+    brand?: BuiltinAgentBrand;
+    gates?: BuiltinAgentGates;
+}): Record<string, RuntimeAgentDefinition>;
+export {};