@yanlinglabs/winter-agent-runtime 0.0.27

package/dist/mcp/lifecycle.d.ts

@@ -0,0 +1,142 @@
+import type { McpServerConfigForProcessTransport } from "@yanlinglabs/winter-agent-sdk";
+import type { McpServerStateSource } from "./state.js";
+import type { McpControlSeam } from "./control-seam.js";
+import type { McpEnvConfig } from "./env.js";
+import { type McpToolInfo, type ConnectedMcpClient } from "./client.js";
+import type { ElicitationAsker } from "./elicitation.js";
+import type { InProcessMcpServer } from "./transports/sdk.js";
+export type McpConfigSourceOrigin = "explicit" | "settings" | "project" | "plugin" | "dynamic";
+export interface McpServerSource {
+    origin: McpConfigSourceOrigin;
+    servers: Readonly<Record<string, unknown>>;
+}
+export interface ResolvedMcpServerEntry {
+    name: string;
+    origin: McpConfigSourceOrigin;
+    config: McpServerConfigForProcessTransport;
+    /**
+     * RULING P5-K (fix wave): present means "this declaration is VALID but must not connect until the
+     * host says so", and the string is the human-readable why. `createMcpLifecycle` gives such an entry
+     * a slot in the `disabled` state carrying this reason, `start()` makes no connection attempt for
+     * it, and `enableSlot(name)` connects it -- a toggle being, by construction, a host decision.
+     *
+     * DISTINCT FROM `rejected`, deliberately. A rejected declaration is WRONG (malformed, reserved
+     * name, unknown type) and never becomes a slot at all -- it is invisible, which is the right answer
+     * for something that could never work. An untrusted project server is not wrong; it is not yet
+     * permitted, and a host that cannot see it cannot permit it.
+     */
+    disabledReason?: string;
+}
+export interface ShadowedMcpServerEntry {
+    name: string;
+    origin: McpConfigSourceOrigin;
+    shadowedBy: McpConfigSourceOrigin;
+}
+/**
+ * Why a declaration was refused, as a CODE a caller can branch on (the `reason` is prose for a
+ * human). WS-23 added the code; every rejection carries one.
+ *
+ * - `invalid_config` -- malformed, an unrecognized `type`, the claudeai-proxy variant, or a bad
+ *   `versionNegotiation` value (`validateServerConfig`).
+ * - `reserved_name` -- the standing server's name (RULING P4-B).
+ * - `sdk_type_from_file_config` -- a `type: "sdk"` entry from a settings/project/plugin FILE. Only
+ *   the host's own `Options.mcpServers` (origin `explicit`) may declare one; see the check itself.
+ */
+export type McpServerRejectionCode = "invalid_config" | "reserved_name" | "sdk_type_from_file_config";
+export interface RejectedMcpServerEntry {
+    name: string;
+    origin: McpConfigSourceOrigin;
+    code: McpServerRejectionCode;
+    reason: string;
+}
+export interface ResolveMcpServerSourcesResult {
+    resolved: ResolvedMcpServerEntry[];
+    shadowed: ShadowedMcpServerEntry[];
+    rejected: RejectedMcpServerEntry[];
+}
+declare function validateServerConfig(raw: unknown): {
+    ok: true;
+    config: McpServerConfigForProcessTransport;
+} | {
+    ok: false;
+    reason: string;
+};
+export { validateServerConfig };
+/**
+ * P7a fix wave (item 5, whole-branch review I-2): the RESERVED name is the SESSION BRAND's.
+ *
+ * `WINTER_SERVER_NAME` is `WINTER_BRAND.mcpServerName` computed at module load, so under a rebrand
+ * this door and `registry.ts`'s read two different names. The registry reserves the SESSION's
+ * `brand.mcpServerName` (per session, via `rebrandStandingServerTools`); this door reserved
+ * `"winter"` forever. Consequences, both real:
+ *
+ *   - a settings/project/explicit server named `acme` passed here, got validated, CONNECTED (a stdio
+ *     child spawned, `slot.client` assigned) and only then hit `registerMcpServerTools`' own
+ *     reserved-name throw -- which is verbatim the defect control.ts records the P4 fix wave closing,
+ *     re-opened for the brand's own name;
+ *   - and a reuser could not name any live server `winter`, a stale reservation for a standing
+ *     server that under their brand is called `acme`.
+ *
+ * The parameter defaults to `WINTER_SERVER_NAME`, so every existing caller and fixture keeps today's
+ * behaviour byte for byte.
+ */
+export declare function resolveMcpServerSources(sources: readonly McpServerSource[], opts: {
+    strictMcpConfig?: boolean;
+    trustedWorkspace: boolean;
+    reservedServerName?: string;
+}): ResolveMcpServerSourcesResult;
+export interface McpDiscoveryCache {
+    get(key: string): McpToolInfo[] | undefined;
+    set(key: string, tools: McpToolInfo[]): void;
+}
+export declare function createInMemoryDiscoveryCache(): McpDiscoveryCache;
+export declare const FIRST_TURN_MCP_WAIT_DEFAULT_MS = 2000;
+export declare function firstTurnMcpWaitDeadlineMs(opts: {
+    strictMcpConfig?: boolean;
+    explicitServers?: Readonly<Record<string, unknown>>;
+    envConfig: Pick<McpEnvConfig, "timeoutMs">;
+}): number;
+export interface McpLifecycleDeps {
+    servers: readonly ResolvedMcpServerEntry[];
+    envConfig: McpEnvConfig;
+    elicitationAsk: ElicitationAsker;
+    inProcessServers?: Readonly<Record<string, InProcessMcpServer>>;
+    discoveryCache?: McpDiscoveryCache;
+    /**
+     * P7a fix wave (item 5, I-2): the name the STANDING server occupies for this session --
+     * `brand.mcpServerName`, not the module-load default. Forwarded to the control seam, whose
+     * `addAndConnect` guard is the second door onto the same rule. Defaults to `WINTER_SERVER_NAME`.
+     */
+    reservedServerName?: string;
+    /** WS-23: the session cwd every stdio server of this lifecycle is spawned in (see `ConnectMcpServerOptions.cwd`). */
+    cwd?: string;
+}
+export type RefreshServerToolsResult = {
+    ok: true;
+    toolNames: string[];
+} | {
+    ok: false;
+    reason: string;
+};
+export interface McpLifecycle {
+    readonly stateSource: McpServerStateSource;
+    readonly controlSeam: McpControlSeam;
+    start(): Promise<void>;
+    dispose(): Promise<void>;
+    listConnectedServerNames(): string[];
+    getConnectedClient(server: string): ConnectedMcpClient | undefined;
+    refreshServerTools(server: string): Promise<RefreshServerToolsResult>;
+}
+export declare function registerSessionMcpLifecycle(sessionId: string, lifecycle: McpLifecycle): () => void;
+export declare function getSessionMcpLifecycle(sessionId: string): McpLifecycle | undefined;
+export declare function createMcpLifecycle(deps: McpLifecycleDeps): McpLifecycle;
+export interface McpLifecycleInternals {
+    hasSlot(name: string): boolean;
+    getSlotOrigin(name: string): McpConfigSourceOrigin | undefined;
+    listSlotNames(): string[];
+    reconnectExisting(name: string): Promise<void>;
+    disableSlot(name: string): void;
+    enableSlot(name: string): Promise<void>;
+    addAndConnect(name: string, origin: McpConfigSourceOrigin, config: McpServerConfigForProcessTransport): Promise<void>;
+    removeSlot(name: string): Promise<void>;
+}

package/dist/mcp/output-cap.d.ts

@@ -0,0 +1,15 @@
+export declare const MCP_PERSISTED_OUTPUT_DIRNAME = "mcp-output";
+export declare function estimateTokens(text: string): number;
+export interface McpOutputCapResult {
+    text: string;
+    truncated: boolean;
+    originalTokens: number;
+    cappedTokens: number;
+    persistedPath?: string;
+}
+export interface McpPersistTarget {
+    sessionDir(): string;
+    serverName: string;
+    toolName: string;
+}
+export declare function capMcpOutput(text: string, maxOutputTokens: number, target: McpPersistTarget): McpOutputCapResult;

package/dist/mcp/state.d.ts

@@ -0,0 +1,24 @@
+export type McpServerStateKind = "pending" | "connected" | "cached" | "failed" | "needsAuth" | "disabled" | "unconfigured";
+export interface McpServerState {
+    name: string;
+    state: McpServerStateKind;
+    errorCode?: string;
+    error?: string;
+    toolNames: string[];
+    /**
+     * WS-23: the protocol revision the server's LIVE connection negotiated (`2025-11-25`, or
+     * `2026-07-28` when `versionNegotiation` selected the modern era). Present only while a live
+     * connection exists -- absent for `pending`/`cached`/`failed`/`needsAuth`, and for an in-process
+     * `sdk` server reported through RULING P4-C's state-only feed (there is no protocol connection to
+     * have a version). Additive: every consumer that predates it reads name/state/toolNames only.
+     */
+    protocolVersion?: string;
+}
+export interface McpServerStateSource {
+    snapshot(): McpServerState[];
+    subscribe(cb: (states: McpServerState[]) => void): () => void;
+    waitForPending(servers: string[] | undefined, deadlineMs: number): Promise<McpServerState[]>;
+}
+export declare function createFakeMcpServerStateSource(initial: readonly McpServerState[]): McpServerStateSource & {
+    transition(name: string, next: McpServerStateKind, extra?: Partial<McpServerState>): void;
+};

package/dist/mcp/test-fixtures.d.ts

@@ -0,0 +1,88 @@
+import { type Transport } from "@modelcontextprotocol/client";
+import { Server, type InputRequiredResult, type ServerContext } from "@modelcontextprotocol/server";
+export interface FixtureContentBlock {
+    type: string;
+    text?: string;
+    [key: string]: unknown;
+}
+export interface FixtureToolResult {
+    content: FixtureContentBlock[];
+    isError?: boolean;
+}
+export interface FixtureTool {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+    annotations?: Record<string, unknown>;
+    _meta?: Record<string, unknown>;
+    /**
+     * `ctx` is the v2 request context: a 2026-07-28 multi-round-trip handler reads the client's
+     * answers off `ctx.mcpReq.inputResponses` and returns `inputRequired(...)` to ask for more (on a
+     * 2025-era connection the SDK's legacy shim turns that same return into a real server->client
+     * `elicitation/create`, so one handler serves both eras).
+     */
+    handler: (args: Record<string, unknown>, server: Server, ctx: ServerContext) => Promise<FixtureToolResult | InputRequiredResult> | FixtureToolResult | InputRequiredResult;
+}
+export interface FixtureResourceBody {
+    text?: string;
+    blobBase64?: string;
+    mimeType?: string;
+}
+export interface FixtureResource {
+    uri: string;
+    name?: string;
+    mimeType?: string;
+    description?: string;
+    read: () => FixtureResourceBody;
+}
+export interface FixtureServerSpec {
+    name?: string;
+    /** Read at REQUEST time, not captured at construction: a test may replace it and then announce the change. */
+    tools?: FixtureTool[];
+    resources?: FixtureResource[];
+    /** WS-23: advertise `tools.listChanged`, so a client wires its list-changed handler. */
+    toolsListChanged?: boolean;
+}
+export declare function defaultFixtureSpec(): FixtureServerSpec;
+export declare function createFixtureMcpServer(spec: FixtureServerSpec): Server;
+export declare function withInMemoryFixture<T>(spec: FixtureServerSpec, fn: (clientTransport: Transport, server: Server) => Promise<T>): Promise<T>;
+export declare function withModernInMemoryFixture<T>(spec: FixtureServerSpec, fn: (clientTransport: Transport, servers: Server[]) => Promise<T>): Promise<T>;
+export declare function withHttpFixture<T>(spec: FixtureServerSpec, fn: (url: URL) => Promise<T>): Promise<T>;
+export declare function withModernHttpFixture<T>(spec: FixtureServerSpec, fn: (url: URL, notify: {
+    toolsChanged(): void;
+}) => Promise<T>): Promise<T>;
+export declare function withSseFixture<T>(spec: FixtureServerSpec, fn: (url: URL) => Promise<T>): Promise<T>;
+export declare function stdioFixtureCommand(): {
+    command: string;
+    args: string[];
+};
+export declare function pingFixtureCommand(opts?: {
+    label?: string;
+    delayMs?: number;
+}): {
+    command: string;
+    args: string[];
+};
+export declare function grandchildSpawningCommand(): {
+    command: string;
+    args: string[];
+};
+import type { McpLifecycle, RefreshServerToolsResult } from "./lifecycle.js";
+import type { ConnectedMcpClient, McpResourceContent, McpResourceInfo, McpToolCallResult, McpToolInfo } from "./client.js";
+export interface FakeConnectedMcpClientOverrides {
+    listTools?: () => Promise<McpToolInfo[]>;
+    listResources?: () => Promise<McpResourceInfo[]>;
+    readResource?: (uri: string, opts?: {
+        timeoutMs?: number;
+    }) => Promise<McpResourceContent[]>;
+    callTool?: (name: string, args: Record<string, unknown>, opts?: {
+        timeoutMs?: number;
+    }) => Promise<McpToolCallResult>;
+    close?: () => Promise<void>;
+}
+export declare function createFakeConnectedMcpClient(serverName: string, overrides?: FakeConnectedMcpClientOverrides): ConnectedMcpClient;
+export interface FakeMcpLifecycleOverrides {
+    connectedServers?: Readonly<Record<string, ConnectedMcpClient>>;
+    refreshServerTools?: (server: string) => Promise<RefreshServerToolsResult>;
+}
+export declare function createFakeMcpLifecycle(overrides?: FakeMcpLifecycleOverrides): McpLifecycle;

package/dist/mcp/transports/__fixtures__/stdio-server.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mcp/transports/http.d.ts

@@ -0,0 +1,5 @@
+import { type Transport } from "@modelcontextprotocol/client";
+import type { McpHttpServerConfig } from "@yanlinglabs/winter-agent-sdk";
+export declare function buildHttpTransport(cfg: McpHttpServerConfig, opts?: {
+    refuseRedirects?: boolean;
+}): Transport;

package/dist/mcp/transports/sdk.d.ts

@@ -0,0 +1,5 @@
+import { type Transport } from "@modelcontextprotocol/client";
+export interface InProcessMcpServer {
+    connect(transport: Transport): Promise<void>;
+}
+export declare function buildSdkTransport(server: InProcessMcpServer): Promise<Transport>;

package/dist/mcp/transports/sse.d.ts

@@ -0,0 +1,3 @@
+import { type Transport } from "@modelcontextprotocol/client";
+import type { McpSSEServerConfig } from "@yanlinglabs/winter-agent-sdk";
+export declare function buildSseTransport(cfg: McpSSEServerConfig): Transport;

package/dist/mcp/transports/stdio.d.ts

@@ -0,0 +1,35 @@
+import { type JSONRPCMessage, type Transport } from "@modelcontextprotocol/client";
+import type { McpStdioServerConfig } from "@yanlinglabs/winter-agent-sdk";
+export declare const STDIO_BASE_ENV_NAMES: readonly ["HOME", "LOGNAME", "PATH", "SHELL", "TERM", "USER"];
+export declare function buildStdioEnv(cfgEnv: Record<string, string> | undefined): Record<string, string>;
+export interface WinterStdioTransportOptions {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    /**
+     * WS-23: the SESSION's cwd, REQUIRED. A spawned `winter` child used to be started in the session
+     * cwd, so an unstated spawn cwd inherited it; an embedded session runs in a Worker, which cannot
+     * have a cwd of its own (`process.cwd()` there is the host daemon's -- `/` under launchd), so a
+     * server with relative `args` (`node ./mcp/server.js`) would start in the wrong tree. Required
+     * rather than defaulted so no caller can silently fall back to the process cwd.
+     */
+    cwd: string;
+}
+export declare class WinterStdioTransport implements Transport {
+    private readonly opts;
+    private child;
+    private readonly readBuffer;
+    private stderrTailBuffer;
+    onclose?: () => void;
+    onerror?: (error: Error) => void;
+    onmessage?: (message: JSONRPCMessage) => void;
+    constructor(opts: WinterStdioTransportOptions);
+    get pid(): number | null;
+    start(): Promise<void>;
+    get stderrTail(): string;
+    private withStderrTail;
+    private processReadBuffer;
+    send(message: JSONRPCMessage): Promise<void>;
+    close(): Promise<void>;
+}
+export declare function buildStdioTransport(cfg: McpStdioServerConfig, cwd: string): WinterStdioTransport;

package/dist/mcp/winter-server.d.ts

@@ -0,0 +1,2 @@
+/** Winter's OWN standing-server name, derived rather than spelled (P7a, D19). */
+export declare const WINTER_SERVER_NAME: string;

package/dist/messaging/reference-adapter.d.ts

@@ -0,0 +1,88 @@
+import type { PermissionMode } from "@yanlinglabs/winter-agent-sdk";
+import { type ChildLike, type RuntimeAddress, type DeliveryOutcome, type GlobalAgentMessage, type RuntimeMessagingAdapter, type CrossSessionInbound, type NotificationQueue, type MessagingRouterSeamWithRoster, type MessagingRuntimeDeps, type SubscriberDirectory } from "@yanlinglabs/winter-agent-sdk/messaging";
+export interface PeerSessionHandle {
+    readonly address: RuntimeAddress;
+    readonly name?: string;
+    readonly cwd?: string;
+    status(): "starting" | "running" | "idle" | "exited" | "unavailable" | "archived";
+    mode(): PermissionMode;
+    bypassAvailable(): boolean;
+    crossSessionInbound?(): CrossSessionInbound | undefined;
+    hasReliableIdleSignal(): boolean;
+    deliver(msg: GlobalAgentMessage): Promise<void>;
+}
+export interface PeerDirectory {
+    list(): PeerSessionHandle[];
+    find(address: RuntimeAddress): PeerSessionHandle | undefined;
+    register(handle: PeerSessionHandle): () => void;
+}
+export declare function createInMemoryPeerDirectory(): PeerDirectory;
+export interface ReferenceAdapterDeps {
+    getChildren(): readonly ChildLike[];
+    peers: PeerDirectory;
+    notifications: NotificationQueue;
+    subscribers: SubscriberDirectory;
+    now(): number;
+}
+export interface ReferenceMessagingAdapter extends RuntimeMessagingAdapter {
+    firePeerIdleTransition(address: RuntimeAddress): void;
+    sweepExpiredIdleSubscriptions(): void;
+    reevaluateHeldFor(address: RuntimeAddress): Promise<Array<{
+        messageId: string;
+        outcome: DeliveryOutcome;
+    }>>;
+    sweepExpiredHeld(): Array<{
+        messageId: string;
+        outcome: DeliveryOutcome;
+    }>;
+}
+export declare function createReferenceMessagingAdapter(deps: ReferenceAdapterDeps): ReferenceMessagingAdapter;
+export interface DefaultMessagingRuntime extends MessagingRuntimeDeps {
+    adapter: ReferenceMessagingAdapter;
+    peers: PeerDirectory;
+    seam: MessagingRouterSeamWithRoster;
+}
+/**
+ * R-7b-4: THIS RUNTIME's answer to "was that throw a policy refusal, or a crash window?"
+ *
+ * `MessagingRuntimeDeps.classifyDeliveryError` is the one behavioural seam the move introduced. The
+ * router core cannot recognise a refusal class belonging to a runtime it does not import, so the
+ * owner supplies the predicate -- and this is Winter's: RULING P4-D's incomparable
+ * recorded-vs-current-parent mode pair, thrown by `ChildHandle.resume()` and deliberately NOT
+ * swallowed by the adapter above, is a clean, side-effect-free policy refusal. Everything else is
+ * indistinguishable from "the effect may already have happened", which is WS-10 §12's
+ * `delivery_uncertain`.
+ *
+ * Exported so `router-wiring.test.ts` can pin both directions on the REAL class.
+ */
+export declare function classifyDeliveryError(err: unknown): "refused" | "uncertain";
+/**
+ * Fix r1 (I3): a message into a session's input stream whose sender cannot be ATTRIBUTED.
+ *
+ * A clean, side-effect-free refusal -- nothing has been written -- so it classifies as `refused`
+ * rather than as WS-10 §12's crash window. Thrown from a session peer's own `deliver`, which is the
+ * only point that knows both the envelope and the stream it would be written to.
+ */
+export declare class UnattributableSenderError extends Error {
+    constructor(reason: string);
+}
+export declare function createDefaultMessagingRuntime(opts?: {
+    now?: () => number;
+    getChildren?: () => readonly ChildLike[];
+}): DefaultMessagingRuntime;
+/**
+ * The registered runtime, IF it is one this file built.
+ *
+ * `getMessagingRuntime()` answers `MessagingRuntimeDeps`, which is all the router core needs and
+ * deliberately carries neither a peer directory nor an idle-transition trigger -- both are
+ * owner-specific (WS-10 §15). The engine's messaging facet needs both to serve
+ * `messaging.subscribe_idle` and `messaging.idle_notice`, so it asks THIS question instead of
+ * casting: a host that registered its OWN runtime has its own session-status event source and its
+ * own directory, and must not have this one's absence papered over with a cast that would throw at
+ * the first call.
+ *
+ * Duck-typed on the two members the engine actually uses, so a host that supplies a compatible
+ * runtime is served too -- the check is about capability, not about identity.
+ */
+export declare function getDefaultMessagingRuntime(): DefaultMessagingRuntime | undefined;
+export declare function ensureDefaultMessagingRuntimeRegistered(): MessagingRouterSeamWithRoster;

package/dist/messaging/router.d.ts

@@ -0,0 +1,8 @@
+import type { PermissionMode } from "@yanlinglabs/winter-agent-sdk";
+import type { MessagingRuntimeDeps } from "@yanlinglabs/winter-agent-sdk/messaging";
+export { MAX_TRACKED_MESSAGE_IDS, rememberBounded, createMessagingRouterSeam, createSubscriberDirectory, callerAddress, sendMessage, listAgents, readNotifications, createMessagingRouter, } from "@yanlinglabs/winter-agent-sdk/messaging";
+export type { MessagingRouterSeamWithRoster, SubscriberDirectory, MessagingRuntimeDeps, CallerContext, SessionCallerContext, SendMessageInput, NotifyOutcome, SendMessageResult, ListAgentsInput, MessagingRouter, RuntimeAddress, ListedRuntimeObject, DeliveryOutcome, } from "@yanlinglabs/winter-agent-sdk/messaging";
+export type { PermissionMode };
+export declare function registerMessagingRuntime(runtime: MessagingRuntimeDeps): void;
+export declare function getMessagingRuntime(): MessagingRuntimeDeps | undefined;
+export declare function resetMessagingRuntimeForTest(): void;

package/dist/paths/project-dir-name.d.ts

@@ -0,0 +1,2 @@
+import { type BrandProfile } from "@yanlinglabs/winter-agent-sdk";
+export declare function resolveProjectDirName(defaultProjectKey: string, env?: Record<string, string | undefined>, brand?: Pick<BrandProfile, "envPrefix">): string;

package/dist/paths/temp.d.ts

@@ -0,0 +1,25 @@
+import type { Stats } from "node:fs";
+import { type BrandProfile } from "@yanlinglabs/winter-agent-sdk";
+export type TempBrand = Pick<BrandProfile, "envPrefix" | "tempRootName">;
+export declare class WinterPathsError extends Error {
+    constructor(message: string);
+}
+export declare function assertOwnedDir(stat: Pick<Stats, "uid"> & {
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+}, pathForError: string): void;
+export declare function resolveTempBase(env?: Record<string, string | undefined>, brand?: Pick<BrandProfile, "envPrefix">): string;
+export interface SessionTempDirOptions {
+    tempProjectKey: string;
+    backendUuid: string;
+    env?: Record<string, string | undefined>;
+    /** P7a (D19): the session's resolved brand. Omitted = `WINTER_BRAND`, i.e. today's names. */
+    brand?: TempBrand;
+}
+export interface SessionTempDirPaths {
+    root: string;
+    scratchpad: string;
+    tasks: string;
+}
+export declare function sessionTempDir(opts: SessionTempDirOptions): SessionTempDirPaths;
+export declare function ensureTasksDir(paths: Pick<SessionTempDirPaths, "tasks">): string;

package/dist/permissions/approvals.d.ts

@@ -0,0 +1,107 @@
+import type { PermissionMode, PermissionUpdate, RuleSource, PermissionDecisionClassification } from "@yanlinglabs/winter-agent-sdk";
+export interface DurableApprovalDisplayMetadata {
+    decisionReason: string;
+    blockedPath?: string;
+}
+export interface ApprovalResolution {
+    mechanism: "hook" | "canUseTool" | "system";
+    at: string;
+    message?: string;
+    transformedInput?: Record<string, unknown>;
+    updatedPermissions?: PermissionUpdate[];
+    decisionClassification?: PermissionDecisionClassification;
+    reason?: string;
+}
+export interface DurableApprovalRecord {
+    runtimeKind: string;
+    sessionId: string;
+    backendSessionId: string;
+    requestId: string;
+    toolUseID: string;
+    agentID?: string;
+    toolName: string;
+    originalInput: Record<string, unknown>;
+    displayMetadata: DurableApprovalDisplayMetadata;
+    permissionSuggestions?: PermissionUpdate[];
+    matchedAskRule?: {
+        source: RuleSource;
+        toolName: string;
+        ruleContent?: string;
+    };
+    policyMode: PermissionMode;
+    policyVersion: number;
+    policyHash?: string;
+    issuedAt: string;
+    expiresAt?: string;
+    state: "pending" | "allowed" | "denied" | "cancelled" | "expired";
+    issuedCwd: string;
+    issuedHome: string;
+    issuedResolvedTargets?: string[];
+    resolution?: ApprovalResolution;
+    consumedAt?: string;
+    consumedResult?: string;
+    consumedIsError?: boolean;
+    consumingAt?: string;
+}
+export declare const WINTER_RUNTIME_KIND = "winter-agent";
+export interface ApprovalResponseInput {
+    outcome: "allowed" | "denied";
+    mechanism: "hook" | "canUseTool" | "system";
+    message?: string;
+    transformedInput?: Record<string, unknown>;
+    updatedPermissions?: PermissionUpdate[];
+    decisionClassification?: PermissionDecisionClassification;
+}
+export interface RespondResult {
+    applied: boolean;
+    record: DurableApprovalRecord;
+}
+export declare class DurableApprovalStoreError extends Error {
+    constructor(message: string);
+}
+export interface RevalidationContext {
+    runtimeKind: string;
+    sessionId: string;
+    backendSessionId: string;
+    toolUseID: string;
+    policyMode: PermissionMode;
+    policyVersion: number;
+    policyHash: string;
+    cwd: string;
+    home: string;
+}
+export type RevalidationAxis = "session" | "toolCall" | "policy" | "paths" | "runtime";
+export type RevalidationVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    axis: RevalidationAxis;
+    reason: string;
+};
+export declare function revalidateApproval(approval: DurableApprovalRecord, ctx: RevalidationContext): RevalidationVerdict;
+export interface SessionKeyLike {
+    sessionId: string;
+}
+export interface ConsumedResultInput {
+    output: string;
+    isError?: boolean;
+}
+export interface DurableApprovalStore {
+    record(approval: DurableApprovalRecord): void;
+    respond(requestId: string, response: ApprovalResponseInput): RespondResult;
+    pendingFor(sessionKey: SessionKeyLike): DurableApprovalRecord[];
+    listFor(sessionKey: SessionKeyLike): DurableApprovalRecord[];
+    get(requestId: string): DurableApprovalRecord | undefined;
+    revalidate(approval: DurableApprovalRecord, ctx: RevalidationContext): RevalidationVerdict;
+    cancelPendingFor(sessionKey: SessionKeyLike, reason: string): void;
+    expire(requestId: string, reason: string): void;
+    markConsumed(requestId: string, result: ConsumedResultInput): void;
+    markConsuming(requestId: string): void;
+}
+export declare function createInMemoryApprovalStore(): DurableApprovalStore;
+export interface ApprovalStoreLocation {
+    winterHome: string;
+    projectKey: string;
+    sessionId: string;
+}
+export declare function createFileDurableApprovalStore(location: ApprovalStoreLocation): DurableApprovalStore;

package/dist/permissions/auto/caches.d.ts

@@ -0,0 +1,53 @@
+import type { PolicyState } from "../policy-state.js";
+import type { PermissionCall, AutoEngineVerdict } from "../evaluator.js";
+export declare function stableHash(value: unknown): string;
+export declare function computePolicyHash(policy: Pick<PolicyState, "mode" | "rules" | "autoConfig">): string;
+export interface EnvHashInputs {
+    cwd: string;
+    home: string;
+    trustedWorkspace: boolean;
+    sessionBypassEnabled?: boolean;
+    additionalDirectories?: string[];
+}
+export declare function computeEnvHash(inputs: EnvHashInputs): string;
+export declare function computeActionFingerprint(call: PermissionCall): string;
+export interface AutoVerdictCacheKey {
+    host?: string;
+    port?: number;
+    policyHash: string;
+    envHash: string;
+    sessionId: string;
+    generation: number;
+    actionFingerprint: string;
+}
+export interface AutoVerdictCacheEntry {
+    verdict: AutoEngineVerdict;
+    cachedAt: string;
+}
+export interface AutoVerdictCache {
+    get(key: AutoVerdictCacheKey): AutoVerdictCacheEntry | undefined;
+    set(key: AutoVerdictCacheKey, entry: AutoVerdictCacheEntry): void;
+}
+export declare function createInMemoryVerdictCache(): AutoVerdictCache;
+export declare const AUTO_FALLBACK_CONSECUTIVE_THRESHOLD = 3;
+export declare const AUTO_FALLBACK_TOTAL_THRESHOLD = 20;
+export interface AutoCounterState {
+    consecutive: number;
+    total: number;
+}
+export declare function isFallbackActive(state: AutoCounterState): boolean;
+export interface AutoCounterStore {
+    get(sessionId: string): AutoCounterState;
+    recordDeny(sessionId: string): AutoCounterState;
+    recordAllow(sessionId: string): AutoCounterState;
+}
+export declare function createInMemoryAutoCounterStore(): AutoCounterStore;
+export declare class AutoCounterStoreError extends Error {
+    constructor(message: string);
+}
+export interface AutoCounterStoreLocation {
+    winterHome: string;
+    projectKey: string;
+    sessionId: string;
+}
+export declare function createFileAutoCounterStore(location: AutoCounterStoreLocation): AutoCounterStore;

package/dist/permissions/auto/config.d.ts

@@ -0,0 +1,37 @@
+import type { RuleSource } from "@yanlinglabs/winter-agent-sdk";
+import type { ParsedRule } from "../grammar.js";
+export interface AutoModeConfig {
+    environment?: string[];
+    allow?: string[];
+    soft_deny?: string[];
+    hard_deny?: string[];
+    classifyAllShell?: boolean;
+    useAutoModeDuringPlan?: boolean;
+}
+export declare const AUTO_MODE_DEFAULT_ENVIRONMENT: readonly string[];
+export declare const AUTO_MODE_DEFAULT_ALLOW: readonly string[];
+export declare const AUTO_MODE_DEFAULT_SOFT_DENY: readonly string[];
+export declare const AUTO_MODE_DEFAULT_HARD_DENY: readonly string[];
+export declare const AUTO_MODE_DEFAULT_USE_AUTO_MODE_DURING_PLAN = true;
+export declare const AUTO_MODE_DEFAULTS_TOKEN = "$defaults";
+export type AutoModeListField = "environment" | "allow" | "soft_deny" | "hard_deny";
+export interface NormalizedAutoModeConfig {
+    environment: string[];
+    allow: string[];
+    soft_deny: string[];
+    hard_deny: string[];
+    classifyAllShell: boolean;
+    useAutoModeDuringPlan: boolean;
+    securityRelevantReplacements: AutoModeListField[];
+}
+export declare function normalizeAutoModeConfig(input: AutoModeConfig | undefined): NormalizedAutoModeConfig;
+export type AutoModeConfigSource = "user" | "managed" | "sdk";
+export declare class AutoModeConfigSourceError extends Error {
+    constructor(source: RuleSource);
+}
+export declare function assertAutoModeConfigSource(source: RuleSource): asserts source is AutoModeConfigSource;
+export type AutoTierVerdict = "hard_denied" | "soft_denied" | "cleared" | "unclassified";
+export declare function resolveAutoTier(category: string | undefined, config: NormalizedAutoModeConfig): AutoTierVerdict;
+export declare const AUTO_SUSPENDED_INTERPRETER_COMMANDS: ReadonlySet<string>;
+export declare const AUTO_SUSPENDED_PACKAGE_MANAGER_COMMANDS: ReadonlySet<string>;
+export declare function isAutoSuspendedAllowRule(rule: ParsedRule, config: Pick<NormalizedAutoModeConfig, "classifyAllShell">): boolean;