@yanlinglabs/winter-agent-sdk 0.0.1

package/dist/protocol/config.d.ts

@@ -0,0 +1,535 @@
+import type { HookSource } from "../permissions/types.js";
+import type { SettingSource } from "../settings/types.js";
+import type { BrandProfile } from "../brand.js";
+/**
+ * `sdk.d.ts:4597-4610`. THREE fields — WS-11 §4 and the plan both name only the first two.
+ * `skipMcpDiscovery` (`4609`) loads the plugin's skills/hooks/agents/commands but does NOT read its
+ * `.mcp.json` or manifest `mcpServers`, for hosts that own the plugin's MCP connections themselves.
+ * `type: 'local'` is a closed one-member literal on the pin (remote/marketplace plugins must first
+ * exist locally, `1846`).
+ */
+export interface SdkPluginConfig {
+    type: "local";
+    path: string;
+    skipMcpDiscovery?: boolean;
+}
+/**
+ * `sdk.d.ts:2159-2164` verbatim (R5-9 as amended after Task 1). THREE arms: a replacement string, a
+ * block array split by `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` (options.ts), or the preset object — whose
+ * `excludeDynamicSections` is NESTED (`2163`) and doc-asserted inert for a string prompt (`2124`).
+ * `preset: 'claude_code'` is the pinned closed literal; Winter's own native preset spelling (BrandProfile.presetName) is
+ * an ALIAS Lane C resolves, deliberately not a widening of this union (a caller passing it to the
+ * pinned SDK would not typecheck, and this type exists to stay drop-in).
+ */
+export type SystemPromptPreset = {
+    type: "preset";
+    preset: "claude_code";
+    append?: string;
+    excludeDynamicSections?: boolean;
+};
+export type SystemPromptOption = string | string[] | SystemPromptPreset;
+/** `sdk.d.ts:963-966`; `OutputFormat = JsonSchemaOutputFormat` (`2207`) is currently a one-member union. */
+export interface JsonSchemaOutputFormat {
+    type: "json_schema";
+    schema: Record<string, unknown>;
+}
+export type OutputFormat = JsonSchemaOutputFormat;
+/**
+ * The main-session skill filter. DISCLOSED: the artifact records this option's doc lines but not its
+ * declared type; capture (4) shows the running engine accepts `'all'` (and that omission is not
+ * "skills off"). `string[] | "all"` is Winter's reading of those two facts — see options.ts.
+ */
+export type SkillsOption = string[] | "all";
+/**
+ * `sdk.d.ts:2848-2858` (R5-11 as amended). The typed result of `Query.rewindFiles(userMessageId,
+ * { dryRun? })` — the pinned parameter is `userMessageId` (`2641`, its own `@param` doc says the
+ * VALUE is a uuid), and both the second parameter and this result are absent from WS-11 §9.
+ *
+ * `skippedLinks` (`2857`) carries a behavioural rule, not just a count (doc `2855`): a tracked path
+ * that resolves to a symlink/hard link/non-regular file, or whose parent no longer resolves where it
+ * did at checkpoint time, or whose backup cannot be safely read, is REFUSED rather than restored —
+ * and the counter is populated on real rewinds only, never on a `dryRun`.
+ *
+ * Types only at Task 2: the control wiring is Task 3's and the mechanism is Lane K's.
+ */
+export interface RewindFilesResult {
+    canRewind: boolean;
+    error?: string;
+    filesChanged?: string[];
+    insertions?: number;
+    deletions?: number;
+    skippedLinks?: number;
+}
+/** The wire form of a rewind request (`sdk.d.ts:4146-4150`): snake_case, and it drops the result. */
+export interface RewindFilesRequest {
+    subtype: "rewind_files";
+    user_message_id: string;
+    dry_run?: boolean;
+}
+/** `sdk.d.ts:4881-4889`: one entry of `system/init.plugins`. `version` is plugin-author-controlled and doc-marked "validate before trusting". */
+export interface InitPluginInfo {
+    name: string;
+    path: string;
+    version?: string;
+}
+export interface RuntimeHookMatcherGroup {
+    matcher?: string;
+    hookCount: number;
+    timeoutSec?: number;
+    source: HookSource;
+    hookNames?: Array<string | null>;
+}
+export type RuntimeHooksConfig = Partial<Record<string, RuntimeHookMatcherGroup[]>>;
+export interface SandboxSettingsConfig {
+    enabled?: boolean;
+    autoAllowBashIfSandboxed?: boolean;
+    excludedCommands?: string[];
+    allowUnsandboxedCommands?: boolean;
+    filesystem?: {
+        allowWrite?: string[];
+        denyWrite?: string[];
+        denyRead?: string[];
+    };
+    network?: {
+        allowedDomains?: string[];
+        deniedDomains?: string[];
+        [key: string]: unknown;
+    };
+}
+export interface McpServerToolPolicy {
+    name: string;
+    permission_policy?: "always_allow" | "always_ask" | "always_deny";
+    org_max_permission?: "allow" | "ask" | "blocked";
+}
+export interface McpStdioServerConfig {
+    type?: "stdio";
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    timeout?: number;
+    alwaysLoad?: boolean;
+}
+export interface McpHttpServerConfig {
+    type: "http";
+    url: string;
+    headers?: Record<string, string>;
+    tools?: McpServerToolPolicy[];
+    timeout?: number;
+    alwaysLoad?: boolean;
+}
+export interface McpSSEServerConfig {
+    type: "sse";
+    url: string;
+    headers?: Record<string, string>;
+    tools?: McpServerToolPolicy[];
+    timeout?: number;
+    alwaysLoad?: boolean;
+}
+export interface WireMcpToolDefinition {
+    name: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    annotations?: {
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        openWorldHint?: boolean;
+        title?: string;
+        idempotentHint?: boolean;
+    };
+    _meta?: Record<string, unknown>;
+}
+export interface McpSdkServerConfig {
+    type: "sdk";
+    name: string;
+    timeout?: number;
+    tools?: WireMcpToolDefinition[];
+}
+export type McpServerConfigForProcessTransport = McpStdioServerConfig | McpHttpServerConfig | McpSSEServerConfig | McpSdkServerConfig;
+export type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;
+export interface RuntimeAgentDefinition {
+    description: string;
+    prompt: string;
+    tools?: string[];
+    disallowedTools?: string[];
+    model?: string;
+    mcpServers?: AgentMcpServerSpec[];
+    criticalSystemReminder_EXPERIMENTAL?: string;
+    skills?: string[];
+    initialPrompt?: string;
+    maxTurns?: number;
+    background?: boolean;
+    memory?: "user" | "project" | "local";
+    effort?: "low" | "medium" | "high" | "xhigh" | "max" | number;
+    permissionMode?: string;
+    observer?: string;
+    observerMessage?: string;
+}
+export interface RuntimeConfig {
+    sessionId: string;
+    cwd: string;
+    model: string;
+    permissionMode?: string;
+    maxTurns?: number;
+    resume?: string;
+    continue?: boolean;
+    forkSession?: boolean;
+    resumeSessionAt?: string;
+    resumeDropsTurn?: boolean;
+    persistSession?: boolean;
+    winterHome?: string;
+    allowedTools?: string[];
+    disallowedTools?: string[];
+    permissions?: {
+        allow?: string[];
+        ask?: string[];
+        deny?: string[];
+        disableBypassPermissionsMode?: boolean;
+    };
+    settingSources?: SettingSource[];
+    managedSettings?: Record<string, unknown>;
+    serverManagedSettings?: Record<string, unknown>;
+    allowDangerouslySkipPermissions?: boolean;
+    hooks?: RuntimeHooksConfig;
+    includeHookEvents?: boolean;
+    permissionPromptToolName?: string;
+    additionalDirectories?: string[];
+    sandbox?: SandboxSettingsConfig;
+    outputsDir?: string;
+    capabilities?: string[];
+    toolSearchEnabled?: boolean;
+    insideSubagent?: boolean;
+    familyMetadata?: {
+        taskNative?: boolean;
+    };
+    mcpServers?: Record<string, McpServerConfigForProcessTransport>;
+    strictMcpConfig?: boolean;
+    toolAliases?: Record<string, string>;
+    agents?: Record<string, RuntimeAgentDefinition>;
+    forwardSubagentText?: boolean;
+    agentId?: string;
+    isolationPinnedCwd?: boolean;
+    systemPrompt?: SystemPromptOption;
+    plugins?: SdkPluginConfig[];
+    skills?: SkillsOption;
+    outputFormat?: OutputFormat;
+    enableFileCheckpointing?: boolean;
+    contextWindowTokens?: number;
+    compactionThreshold?: number;
+    trustedWorkspace?: boolean;
+    plansDirectory?: string;
+    outputStyle?: string;
+    provider?: ProviderSelection;
+    fallbackModel?: string;
+    thinking?: ThinkingConfig;
+    effort?: EffortLevel;
+    /**
+     * @deprecated Use `thinking` instead.
+     *
+     * CONSUMER AND RULE, named because this field is inert until something applies it and a mapping
+     * with no owner is how a deprecated option quietly keeps its old semantics.
+     *
+     * OWNER: `packages/runtime/src/provider/selection.ts` (T3), at the point where a session's
+     * effective `ThinkingConfig` is resolved and handed to an adapter — NOT the adapter itself, so
+     * every family sees one already-resolved shape rather than each re-deriving it.
+     *
+     * RULE (R6-E, from the pinned deprecation text at `sdk.d.ts:1750-1757`):
+     *   1. `thinking`, when present, WINS outright — the pin states that precedence twice (`1732`,
+     *      `8215`) — and `maxThinkingTokens` is then ignored entirely, not merged.
+     *   2. Otherwise `0` maps to `{ type: "disabled" }`.
+     *   3. Otherwise ANY other value maps to `{ type: "adaptive" }` — deliberately NOT
+     *      `{ type: "enabled", budgetTokens: N }`. This is the trap the pin calls out: on a modern
+     *      model the field is reinterpreted as on/off, so forwarding `maxThinkingTokens: 8000` as a
+     *      budget of 8000 would be a different request from the one the pinned runtime makes.
+     *   4. An adapter MAY re-resolve `enabled` to `adaptive` for a model whose evidence says
+     *      adaptive-only (capture (F) observed exactly that), recorded in the descriptor's `reasoning`
+     *      evidence — that is a per-model adapter rule, downstream of this mapping.
+     */
+    maxThinkingTokens?: number;
+    includePartialMessages?: boolean;
+    maxBudgetUsd?: number;
+    providerStallTimeoutMs?: number;
+    keychainService?: string;
+    autoClassifier?: AutoClassifierConfig;
+    advisor?: AdvisorConfig;
+    /**
+     * P7a (D19): the RESOLVED brand profile — every Winter-owned name this session runs under.
+     *
+     * ALWAYS the full profile, never a partial and never absent from a config `query()` built: the
+     * WRAPPER resolves (`resolveBrand(Options.brand)`, validated at construction), and the runtime
+     * NEVER defaults. That asymmetry is the whole design — a runtime that filled in Winter's own
+     * names when the field was missing would silently un-brand a reuser's session on any path that
+     * forgot to thread it, which is exactly the failure the profile exists to make impossible.
+     *
+     * Optional on the TYPE only, for the configs this repository hand-builds in tests and for a
+     * pre-P7a wire message; a runtime reader that finds it absent is reading a config no `query()`
+     * produced and should say so rather than substituting.
+     *
+     * `keychainService` above is the DEPRECATED standalone alias for `brand.keychainService` (P6's
+     * own R6-10 field). The wrapper folds it: when the host sets it, its value is what lands in
+     * `brand.keychainService` too, so the two can never disagree on the wire.
+     */
+    brand?: BrandProfile;
+}
+/**
+ * The pinned effort vocabulary, `sdk.d.ts:586` (derived-shapes-p6.md item (c)).
+ *
+ * **No numeric member, deliberately (R6-E).** The numeric form exists in the pin on exactly one
+ * surface — `AgentDefinition.effort` (`sdk.d.ts:87`), a per-subagent field — and `Options.effort`
+ * (`1749`) is the bare union. Widening this to `| number` would be an Options-parity divergence.
+ * provider-runtime's `TurnRequest.effort` DOES keep `number`, because a child carrying a numeric
+ * effort reaches an adapter through that seam; the adapter maps it to the nearest verified tier of
+ * the model's own `reasoning.efforts` (the pin states no unit or mapping — a documented absence,
+ * OQ-P6-2 — so this is gap-filling, not divergence).
+ */
+export type EffortLevel = "low" | "medium" | "high" | "xhigh" | "max";
+/**
+ * `sdk.d.ts:8216` — three arms, exactly these spellings (derived-shapes-p6.md item (c)).
+ *
+ * Two declaration facts the option's own JSDoc contradicts, resolved in the declaration's favour:
+ * `budgetTokens` is OPTIONAL on the `enabled` arm (`8230`), and `display` exists on `adaptive` and
+ * `enabled` but NOT on `disabled`. The clearing form (`display: null`) exists only on the imperative
+ * surfaces (`setMaxThinkingTokens`), never in `ThinkingConfig` — so it is absent here too.
+ */
+export type ThinkingConfig = {
+    type: "adaptive";
+    display?: "summarized" | "omitted";
+} | {
+    type: "enabled";
+    budgetTokens?: number;
+    display?: "summarized" | "omitted";
+} | {
+    type: "disabled";
+};
+/**
+ * R6-10: an OPAQUE reference to credential material, never the material itself. Descriptors and
+ * config alike carry references; the store resolves one at the last responsible moment.
+ *
+ * - `keychain` — one record per provider/account, `account = "<providerId>:<accountId>"`, service
+ *   from `Options.keychainService ?? WINTER_BRAND.keychainService`. Retires the single fixed secret name.
+ * - `env` — a host NAMES the variable explicitly. Ambient keys are NEVER scanned implicitly: an
+ *   `ANTHROPIC_API_KEY` sitting in the environment does not become a credential by existing.
+ * - `file` — a shared-credentials file, a GCP service-account JSON, or a raw single-value file.
+ * - `inline` — a host responsibility: never persisted by the SDK, redacted in every frame and log.
+ * - `aws-default-chain` — env + shared-credentials file only this phase (R6-16: no IMDS/STS).
+ * - `none` — a local endpoint that needs no credential. NOT "unauthenticated by accident".
+ */
+export type CredentialRef = {
+    kind: "keychain";
+    account: string;
+    service?: string;
+} | {
+    kind: "env";
+    name: string;
+} | {
+    kind: "file";
+    path: string;
+    format: "aws-shared-credentials" | "gcp-service-account-json" | "raw";
+    profile?: string;
+} | {
+    kind: "inline";
+    value: string;
+} | {
+    kind: "aws-default-chain";
+} | {
+    kind: "none";
+};
+/**
+ * Non-secret connection metadata (WS-13 §6: "the selected account/region/project/deployment is
+ * recorded as non-secret connection metadata — never forced through one bearer-token abstraction").
+ *
+ * The wire twin of provider-runtime's `ConnectionProfile`, minus its `providerId` (which is
+ * `ProviderSelection.providerId` here). `baseUrl` is a USER endpoint and goes through the endpoint
+ * policy — generated descriptor endpoints are immutable and never come from this shape (R6-11).
+ */
+export interface ProviderConnectionConfig {
+    baseUrl?: string;
+    headers?: Record<string, string>;
+    region?: string;
+    project?: string;
+    location?: string;
+    deployment?: string;
+    apiVersion?: string;
+    local?: boolean;
+    /**
+     * P7a carry (Lane D): WHERE this connection's `baseUrl` came from, which is what the endpoint
+     * policy actually needs to know.
+     *
+     * `"reviewed"` — the catalog's own generated/reviewed endpoint, COPIED into the profile by the
+     * runtime's `connectionFrom`. `"user"` — a host- or user-entered endpoint.
+     *
+     * WHY IT EXISTS. The two are byte-identical strings by the time they reach the profile, and the
+     * policy has been forced to treat both as user endpoints because it could not tell them apart —
+     * which silently downgrades every multi-provider row (whose reviewed endpoint is always copied)
+     * out of the privileged-header path in production while adapter fixtures, which pass a generated
+     * base URL directly, keep passing. Recording the ORIGIN is what lets the policy answer honestly.
+     *
+     * ABSENT means unknown, and unknown must be treated as `"user"` — the conservative reading. The
+     * evaluation rules are Lane D's (`provider-runtime/src/endpoint-policy.ts`); the spine declares
+     * the field so producer and consumer can land in either order.
+     */
+    endpointOrigin?: "reviewed" | "user";
+}
+/**
+ * R6-9: which provider a bare model id resolves against, plus how to reach and authenticate it.
+ *
+ * `allowUnlisted` sits HERE rather than on `ConnectionProfile` (whose shape T2's brief pins
+ * verbatim): it is a selection-policy bit, not connection metadata. R6-F admits it only for a
+ * local/gateway provider whose `liveCatalogAuthority` is not `authoritative`; anywhere else the
+ * registry ignores it and an unlisted id is still a typed `unknown-model` refusal, because WS-13
+ * §8.3's model-id validation is the whole point of the catalog.
+ */
+export interface ProviderSelection {
+    providerId: string;
+    authRef?: CredentialRef;
+    connection?: ProviderConnectionConfig;
+    allowUnlisted?: boolean;
+}
+/** R6-14: the classifier's own route — resolved through the SAME selection path as the session model. */
+export interface AutoClassifierConfig {
+    model: string;
+    authRef?: CredentialRef;
+}
+/**
+ * The advisor/reviewer backend's own model selection (P2 carry, wired in T10). Same selection path.
+ *
+ * `authRef` (P6 fix wave, Ruling E-1) mirrors `AutoClassifierConfig.authRef`: the advisor's OWN
+ * credential, for a reviewer on another provider than the session's. A cross-provider advisor never
+ * inherits the session's credential -- without a ref here, and without a keychain record for the
+ * advisor's provider, the advisor's provider refuses with a typed `no-credential-for-provider`.
+ */
+export interface AdvisorConfig {
+    model: string;
+    authRef?: CredentialRef;
+}
+/**
+ * The pinned `ModelInfo` (`sdk.d.ts:1261-1300`): three required fields, six optional.
+ *
+ * `description` being REQUIRED is the notable one — a catalog row generated from an upstream
+ * extraction with no description cannot satisfy this shape without inventing text. The four
+ * `supports*` booleans are the pin's ENTIRE capability vocabulary for a model, and each is OMITTED
+ * when unknown rather than reported `false` (R6-I): absent means unknown, and capture (J) observed
+ * the omission varying per capability within one response.
+ */
+export interface ModelInfo {
+    value: string;
+    resolvedModel?: string;
+    displayName: string;
+    description: string;
+    supportsEffort?: boolean;
+    supportedEffortLevels?: Array<"low" | "medium" | "high" | "xhigh" | "max">;
+    supportsAdaptiveThinking?: boolean;
+    supportsFastMode?: boolean;
+    supportsAutoMode?: boolean;
+}
+/**
+ * The pinned `AccountInfo` (`sdk.d.ts:23-33`). EVERY field optional; an empty object is valid, and
+ * capture (J) observed exactly three keys present under API-key auth.
+ *
+ * `apiKeySource` here is a BARE STRING while `system/init.apiKeySource` is the closed `ApiKeySource`
+ * union — the same concept typed twice, differently, in one pinned declaration. Reproduced rather
+ * than reconciled: a Winter consumer that narrowed this one would be narrowing something the pin
+ * left open.
+ */
+export interface AccountInfo {
+    email?: string;
+    organization?: string;
+    subscriptionType?: string;
+    tokenSource?: string;
+    apiKeySource?: string;
+    apiProvider?: "firstParty" | "bedrock" | "vertex" | "foundry" | "anthropicAws" | "anthropicGoogleCloud" | "mantle" | "gateway";
+}
+/**
+ * One option as a host renders it (WS-13c §7).
+ *
+ * `resolvesTo` is present only when the slot actually resolves for THIS session — a credential is
+ * configured and the provider is enabled. Its absence is the honest "this option exists in the
+ * lineup but nothing here can serve it", which is what lets a switcher grey an entry rather than
+ * offer it and fail at turn time.
+ */
+export interface SlotView {
+    name: string;
+    canonicalModelId: string;
+    description: string;
+    reason: string;
+    resolvesTo?: {
+        providerId: string;
+        key: string;
+    };
+}
+/**
+ * The slots a session is CURRENTLY offering, and why they are those slots (WS-13c §3).
+ *
+ * `source` is the whole provenance story in one field, and every member is a distinct, observable
+ * state a host may want to explain:
+ *   `family-default`  the effective main model's family has curated slots, and these are they.
+ *   `custom`          `settings.modelSlots` replaced the set (D27).
+ *   `claude-pinned`   the effective main model is a Claude model, so the set is the pinned four and
+ *                     any custom slots were IGNORED and recorded (D25, "for now").
+ *   `own-model`       the family has no curated slots (or is `other`), so the session renders its
+ *                     own effective model as the single slot (D26's minimum of one).
+ */
+export interface ActiveSlotSet {
+    family: string;
+    source: "family-default" | "custom" | "claude-pinned" | "own-model";
+    slots: SlotView[];
+}
+/**
+ * P7a carry (Lane D): whether this session can currently SERVE a catalog row — a TRI-STATE, not a
+ * boolean.
+ *
+ * `"present"` a credential is configured for the row's provider and the provider is not disabled.
+ * `"absent"`  we know there is none.
+ * `"unknown"` nobody has probed this provider yet, so the honest answer is "we do not know".
+ *
+ * WHY THE BOOLEAN WAS WRONG. A boolean has to collapse `unknown` onto one of the other two, and
+ * both collapses lie: `false` tells a model switcher a perfectly usable row is unavailable, and
+ * `true` (the shape the cold first paint originally shipped) claimed every row in a 604-model
+ * catalog was servable against an empty credential store. A host renders three states differently —
+ * available, unavailable, and "sign in to find out" — so the type carries three.
+ *
+ * PUBLIC-SHAPE CHANGE, declared at the spine and made TRUTHFUL by Lane D: until Lane D's
+ * credential-view work lands, `family-listing.ts` maps its existing boolean to `"present"`/
+ * `"absent"` and never emits `"unknown"`. Consumers must therefore already handle all three.
+ */
+export type ModelRowServable = "present" | "absent" | "unknown";
+/**
+ * `Query.listModelFamilies()`'s answer (WS-13c §7): the active set first, then everything behind
+ * "more options".
+ *
+ * `active` is `undefined` ONLY for a session running a scripted test double, which has no effective
+ * model to derive a family from. It is not a "no families" signal — that is `families: []`.
+ */
+export interface ModelFamilyListing {
+    active: ActiveSlotSet | undefined;
+    families: Array<{
+        id: string;
+        displayName: string;
+        vendor: string;
+        slots: SlotView[];
+        models: Array<{
+            canonicalModelId: string;
+            displayName: string;
+            rows: Array<{
+                key: string;
+                providerId: string;
+                status: string;
+                pricingBasis: string;
+                servable: ModelRowServable;
+            }>;
+        }>;
+    }>;
+}
+/**
+ * One entry of `settings.modelSlots` (WS-13c §5, D27): the user's own facing name for a model.
+ *
+ * `model` is a `canonicalModelId` OR a catalog key — both spellings are things a user reasonably has
+ * to hand, and validation resolves either. `description` overrides Winter's own slot text; absent
+ * means "use Winter's description for that canonical model, else the row's displayName".
+ */
+export interface ModelSlotSetting {
+    name: string;
+    model: string;
+    provider?: string;
+    description?: string;
+}