@yanlinglabs/winter-agent-runtime 0.0.27

package/dist/tools/registry.d.ts

@@ -0,0 +1,423 @@
+import type { PermissionMode, BackgroundTaskMessage, BrandProfile, SettingSource } from "@yanlinglabs/winter-agent-sdk";
+import type { ReadAccessProbe } from "../permissions/evaluator.js";
+import type { SessionReadState } from "./read-state.js";
+import type { SandboxSettings } from "../sandbox/profile.js";
+import type { SpawnChildRequest, ChildHandle } from "../subagents/child-handle.js";
+export interface JSONSchema {
+    type?: string | readonly string[];
+    properties?: Record<string, JSONSchema>;
+    items?: JSONSchema | readonly JSONSchema[];
+    required?: readonly string[];
+    enum?: readonly unknown[];
+    const?: unknown;
+    description?: string;
+    additionalProperties?: boolean | JSONSchema;
+    oneOf?: readonly JSONSchema[];
+    anyOf?: readonly JSONSchema[];
+    allOf?: readonly JSONSchema[];
+    minimum?: number;
+    maximum?: number;
+    minItems?: number;
+    maxItems?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    [key: string]: unknown;
+}
+export interface ToolAnnotations {
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    openWorldHint?: boolean;
+    title?: string;
+    idempotentHint?: boolean;
+}
+export type PermissionClass = "read" | "edit" | "execute" | "network" | "interaction" | "messaging" | "task" | "mode" | "mcp" | "hosted";
+export interface AvailabilityPredicate {
+    modes?: readonly PermissionMode[];
+    platforms?: readonly NodeJS.Platform[];
+    requiresFeatures?: readonly string[];
+    requiresToolSearchDisabled?: true;
+    requiresToolSearchEnabled?: true;
+    hiddenWhenFamilyTaskNative?: true;
+    insideSubagent?: false;
+}
+export type ToolDisposition = "implement-now" | "implement-later" | "correctly-absent" | "winter-backed-equivalent" | "winter-backed-later";
+export interface ToolDescriptor {
+    canonicalName: string;
+    advertisedName: string;
+    source: "builtin" | "mcp" | "sdk" | "plugin" | "host";
+    inputSchema: JSONSchema;
+    outputSchema?: JSONSchema;
+    description: string;
+    searchHint?: string;
+    annotations?: ToolAnnotations;
+    exposure: "eager" | "deferred" | "hidden";
+    permissionClass: PermissionClass;
+    availability: AvailabilityPredicate;
+    capabilityRequirements: string[];
+    disposition: ToolDisposition;
+    versionIntroduced?: string;
+    deferred?: boolean | readonly PermissionMode[];
+    alwaysLoad?: boolean;
+    _meta?: Record<string, unknown>;
+    interaction?: "required";
+}
+export interface ToolResultPayload {
+    output: string;
+    isError?: boolean;
+}
+/** See `ToolExecutionContext.permission`. */
+export interface ToolCallPermission {
+    explicitApproval: "prompt" | "rule";
+}
+/** What the engine may hand the adapter per call; both optional, both absent for a hand-made call. */
+export interface ToolCallExecuteOptions {
+    signal?: AbortSignal;
+    /** The permission decision's `explicitApproval`, when it carried one. */
+    explicitApproval?: "prompt" | "rule";
+}
+export interface ToolExecutionContext {
+    cwd: string;
+    home: string;
+    /**
+     * Phase 5 fix wave, I1: the RESOLVED winter root for this session (`<PREFIX>HOME` when set),
+     * DISTINCT from `home` above, which is the OS home directory.
+     *
+     * The two are not interchangeable and confusing them is a shipped-bug class in this codebase --
+     * see `SkillIndexOptions.winterHome`'s own header. A tool that needs to name Winter's own storage
+     * (the agents user tier, a seatbelt deny, the checkpoint store) reads THIS; a tool that needs the
+     * user's home for a `~`-anchored path reads `home`. Absent for a hand-built context, in which case
+     * every consumer falls back to `<home>/<brand.homeDirName>/...` -- the pre-fix behaviour.
+     */
+    winterHome?: string;
+    /**
+     * WS-21 §3.7/§6.3 item 11 (fix round 1, item 4): the shared runtime home's durable-paths root
+     * (`config.storeHome`), preferred over `winterHome` for the SAME two consumers `winterHome`'s own
+     * header names when a real seatbelt profile needs to fence durable content -- `bash.ts`'s own
+     * `buildRunCommandOptions` is the one production reader (`sandbox/spawn.ts`'s
+     * `buildSeatbeltProfile`, in turn). Absent falls back to `winterHome`, byte-identical to
+     * pre-WS-21 behaviour.
+     */
+    storeHome?: string;
+    /**
+     * WS-21 §6.3 item 1 (durable-write audit sibling, fix round 2): the session's ENABLED plugins
+     * that ship a `workflows/` directory, for the Workflow tool's `<plugin>:<name>` resolution
+     * (`workflows/store.ts`'s `resolveWorkflowByName`). Fixed per incarnation, like every other
+     * plugin-derived value this codebase threads. Absent means no qualified workflow name ever
+     * resolves, matching every pre-fix-round-2 caller.
+     *
+     * Fix round 4 (minors, M-3's last bullet): also carries `workflowsPaths` -- see
+     * `engine.ts`'s own `EngineOptions.pluginWorkflows` for why this widened rather than a new field.
+     */
+    pluginWorkflows?: readonly {
+        name: string;
+        workflowsPath?: string;
+        workflowsPaths?: readonly string[];
+    }[];
+    /**
+     * SV-5 fix round 3 (I-4): the session's resolved `settingSources` (`RuntimeConfig.settingSources`),
+     * for the Workflow tool's project/user tier resolution (`workflows/store.ts`'s
+     * `resolveWorkflowByName`) -- the same fact `production-wiring.ts` already resolves once per
+     * incarnation for skills/agents/rules/MCP. Absent means every tier is allowed, matching claude's
+     * own `settingSources` default and every pre-fix-round-3 caller.
+     */
+    settingSources?: readonly SettingSource[];
+    /**
+     * P7a (D19): the session's RESOLVED brand profile, threaded from `RuntimeConfig.brand`.
+     *
+     * Every tool that names a Winter-owned surface from inside its own executor -- the project
+     * dot-dir a workflow/worktree/cron file lives under, an env variable, the instructions file --
+     * reads it from HERE rather than spelling one. OPTIONAL for the same reason as
+     * `insideSubagent`/`trustedWorkspace` (~25 hand-built test contexts with no shared builder);
+     * ABSENT READS AS `WINTER_BRAND`, which is byte-identical to the behaviour before this field.
+     */
+    brand?: BrandProfile;
+    sessionId: string;
+    readState: SessionReadState;
+    emitFrame: (frame: BackgroundTaskMessage) => void;
+    emitToolReference?: (names: string[]) => void;
+    permissions: {
+        probeReadAccess(filePath: string): ReadAccessProbe;
+    };
+    tempDir: string;
+    sandboxSettings: SandboxSettings;
+    /**
+     * Phase 6 Task 3 (R6-6, P4 carry): the engine's per-turn abort signal.
+     *
+     * ABORTED when the turn is interrupted. Bash and Monitor honour it -- their process-group kill
+     * already existed, and this is the channel that reaches it: before this field the interrupt was a
+     * raced Promise the engine stopped waiting on while the child kept running to completion.
+     * An executor that ignores the field behaves exactly as before.
+     *
+     * OPTIONAL, matching `insideSubagent`/`emitToolReference` and for the identical reason: ~25
+     * `impl/*.test.ts` files build a `ToolExecutionContext` by hand with no shared builder, and a
+     * required field would force a throwaway stub into every one of them.
+     */
+    signal?: AbortSignal;
+    outDir?: string;
+    insideSubagent?: boolean;
+    isolationPinnedCwd?: boolean;
+    trustedWorkspace?: boolean;
+    agentId?: string;
+    toolUseId?: string;
+    agents?: Readonly<Record<string, unknown>>;
+    /**
+     * Spawn-surface parity: the SESSION's environment (the engine's `env` option, else the process
+     * env) -- the per-session kill switches the Agent tool reads (`loadAgentDefinitions`' built-in
+     * gates, the background kill switch, the fork gate's env fallback) come from here, exactly like
+     * `limits.ts`'s own per-session env reads. Absent = `process.env`.
+     */
+    env?: Readonly<Record<string, string | undefined>>;
+    /** Spawn-surface parity (R-S5): this session's resolved fork gate (RuntimeConfig.forkSubagent, else the env fallback). Absent = resolve from `env`. */
+    forkSubagentEnabled?: boolean;
+    /** I4 (fix wave): this session's resolved background-by-default opt-out (RuntimeConfig.backgroundByDefault, else the env fallback). Absent = resolve from `env` (`subagents/policy.ts`'s `resolveBackgroundByDefaultEnabled`). */
+    backgroundByDefault?: boolean;
+    /** Spawn-surface parity (R-S5): this engine is itself a forked worker (RuntimeConfig.insideFork) -- a fork may not fork again. */
+    insideFork?: boolean;
+    /**
+     * Review r2 finding 2 (whole-branch): the session's ONE rejection reporter for a filesystem
+     * `agents/*.md` file `loadAgentDefinitions` could not parse (`tools/impl/agent.ts`'s own call
+     * passes it straight through as `onReject`). Typed structurally (the same discipline `agents?`
+     * above documents) rather than importing `subagents/definitions.ts`'s own `AgentDefinitionRejection`
+     * here. Absent = silent-skip, the pre-existing behavior for every hand-built test context.
+     */
+    onAgentDefinitionRejected?: (rejection: {
+        source: "user" | "project" | "plugin";
+        filePath: string;
+        reason: string;
+    }) => void;
+    /**
+     * Spawn-surface parity (research §A8): the names this session currently ADVERTISES to its model
+     * (canonical). The Agent tool's background launch result reads it to decide whether the model can
+     * read the task's output file at all (`Read`/`Bash` present). A getter: the set can move mid-run.
+     */
+    advertisedToolNames?: () => readonly string[];
+    /**
+     * SDK 0.0.16 Lane P (R3b §4): this session's live Agent-type availability -- `Agent(type)` deny
+     * rules, `allowedAgentTypes`, and "every tool it may use is denied" -- built fresh per call
+     * (never cached) so a live rule/settings change is reflected without a restart, mirroring
+     * `probeReadAccess`'s own "cheap, side-effect-free, re-derived per call" precedent.
+     * `tools/impl/agent.ts` is the one consumer: it resolves a requested `subagent_type` against the
+     * FULL definitions map (a denied/not-allowed type still names itself in the refusal, never a bare
+     * "not found"), then asks this closure whether the resolved name is available right now and why
+     * not. Structurally typed (no `SourcedRuleEntry`/evaluator.ts import here, matching this
+     * interface's own `onAgentDefinitionRejected` precedent immediately above) -- engine.ts builds
+     * both the name list and the per-type message from its own `permissions/evaluator.ts` +
+     * `subagents/availability.ts` imports, and hands this seam only the already-formatted result.
+     */
+    agentAvailability?: () => {
+        /** Names available right now -- deny rules, allowedAgentTypes and all-tools-denied already applied. Used for "Available agents: ..." refusal text and the omitted-type default's own availability check. */
+        availableNames: readonly string[];
+        /**
+         * Exact refusal prose for a type that EXISTS in the full definitions map but is refused for a
+         * reason OTHER than `allowedAgentTypes` (a per-type deny rule, or "every tool it may use is
+         * denied") -- `undefined` when neither applies (including when the type does not exist at all,
+         * or is merely excluded by `allowedAgentTypes` -- claude reuses the plain not-found shape for
+         * that case, built by the caller from `availableNames` above).
+         */
+        unavailableMessage: (agentType: string) => string | undefined;
+    };
+    /**
+     * HOW THIS CALL WAS PERMITTED -- present only when it was EXPLICITLY approved.
+     *
+     * An executor cannot prompt mid-call, so a tool whose safety depends on "did a person (or a rule
+     * naming this exact target) consent to THIS call?" has to be told. `explicitApproval` is the
+     * permission decision's own marker (`PermissionDecisionRecord.explicitApproval`), carried verbatim:
+     *   - `"prompt"` -- a permission request for this call was answered allow;
+     *   - `"rule"`   -- a standing allow rule names this call's target exactly.
+     * ABSENT means the call was allowed by the session's mode, a broad rule, a pre-approving hook or
+     * the classifier -- or that this context was hand-built. An executor must read absence as "not
+     * explicitly approved", never the other way round.
+     *
+     * One consumer today: `WebFetch`, for a private-address target under the `"ask"` policy.
+     */
+    permission?: ToolCallPermission;
+    session: {
+        setCwd(p: string): void;
+        addBoundedRoot(p: string): void;
+        removeBoundedRoot(p: string): void;
+        getSessionRoot(): string;
+        setSessionRoot(p: string): void;
+        setPermissionMode(mode: PermissionMode): void;
+        getBoundedRoots(): string[];
+        getPermissionMode(): PermissionMode;
+        spawnChild?(req: SpawnChildRequest): Promise<ChildHandle>;
+    };
+}
+export interface ToolExecutor {
+    execute(input: unknown, ctx: ToolExecutionContext): Promise<ToolResultPayload>;
+}
+export interface RegisteredTool {
+    descriptor: ToolDescriptor;
+    executor?: ToolExecutor;
+    extractPaths?: (input: unknown) => {
+        reads: string[];
+        writes: string[];
+    };
+}
+export declare function registerTool(t: RegisteredTool): void;
+export declare function replaceExecutor(canonicalName: string, executor: ToolExecutor, extractPaths?: RegisteredTool["extractPaths"]): void;
+export declare function getRegisteredTool(canonicalName: string): RegisteredTool | undefined;
+export declare function listRegisteredTools(): readonly RegisteredTool[];
+/**
+ * The ONLY names a host-generated registration may claim (fix round 1, M1).
+ *
+ * WS-06 §3.6 declares `StructuredOutput`'s `input_schema` as "GENERATED per-call from the caller's
+ * requested output schema -- never one static interface", and its own P3 descriptor
+ * (descriptors/structured-output.ts) calls its schema a placeholder the host substitutes. That
+ * declaration is what makes the name generatable; nothing else in the catalogue carries it.
+ *
+ * Defined HERE rather than in structured/seam.ts so the registry depends on nothing to enforce its
+ * own guard; that module re-exports it for Lane K.
+ */
+export declare const HOST_GENERATABLE_TOOL_NAMES: ReadonlySet<string>;
+export declare function registerHostGeneratedTool(t: RegisteredTool): () => void;
+export declare function unregisterToolForTest(canonicalName: string): void;
+export interface McpToolDefinition {
+    name: string;
+    description?: string;
+    inputSchema: JSONSchema;
+    outputSchema?: JSONSchema;
+    annotations?: ToolAnnotations;
+    _meta?: Record<string, unknown>;
+}
+export declare function onRegistryChange(cb: () => void): () => void;
+export declare function rebrandStandingServerTools(renames: ReadonlyArray<{
+    from: string;
+    to: string;
+}>, serverName: string): () => void;
+export declare function registerMcpServerTools(server: string, incomingTools: readonly McpToolDefinition[], opts: {
+    alwaysLoad?: boolean;
+    deferredDefault: boolean | readonly PermissionMode[];
+}): void;
+/**
+ * Fix round 20: the live MCP server that registered `canonicalName` through `registerMcpServerTools`,
+ * or `undefined` for any other registration (a static descriptor, a standing-server twin). The
+ * registry is process-wide; a run's advertised partition uses this to keep only the MCP tools of
+ * servers that run can see (engine.ts's `computeAdvertisedPartition`).
+ */
+export declare function mcpServerOwningTool(canonicalName: string): string | undefined;
+export declare function unregisterMcpServerTools(server: string): void;
+export interface LoadedToolSet {
+    isLoaded(name: string): boolean;
+    load(names: string[]): {
+        loaded: string[];
+        unknown: string[];
+    };
+    reset(evidenced: string[]): void;
+    snapshot(): string[];
+}
+export declare function createLoadedToolSet(): LoadedToolSet;
+export declare function onCompaction(loaded: LoadedToolSet, evidencedToolNames: readonly string[]): void;
+export interface DeferralActivation {
+    enableToolSearch: "unset" | "true" | "false" | "auto" | {
+        auto: number;
+    };
+    providerSupportsToolSearch: boolean;
+    deferrableContextShare: number;
+}
+export declare function isDeferralActive(activation: DeferralActivation): boolean;
+export declare function resolveDeferral(descriptor: ToolDescriptor, mode: PermissionMode, activation: DeferralActivation): "eager" | "deferred" | "hidden";
+export interface AdvertisedPartition {
+    eager: ToolDescriptor[];
+    deferred: ToolDescriptor[];
+    hidden: ToolDescriptor[];
+}
+export declare function partitionAdvertisedTools(cfg: AdvertisedSetInputs, activation: DeferralActivation): AdvertisedPartition;
+export declare function isLoadFirstBlocked(toolName: string, mode: PermissionMode, activation: DeferralActivation, loaded: LoadedToolSet): boolean;
+export interface AdvertisedSetInputs {
+    mode: PermissionMode;
+    platform?: NodeJS.Platform;
+    features?: Readonly<Record<string, boolean>>;
+    capabilities?: readonly string[];
+    familyMetadata?: {
+        taskNative?: boolean;
+    };
+    toolSearchEnabled?: boolean;
+    insideSubagent?: boolean;
+    tools?: readonly string[];
+    allowedTools?: readonly string[];
+    disallowedTools?: readonly string[];
+}
+export declare function isToolAvailable(descriptor: ToolDescriptor, cfg: AdvertisedSetInputs): boolean;
+export interface RuntimeDerivedCapability {
+    token: string;
+    probeTool: string;
+    requiresSessionFact?: keyof SessionCapabilityFacts;
+}
+export interface SessionCapabilityFacts {
+    hasMcpServers: boolean;
+}
+export declare const RUNTIME_DERIVED_CAPABILITIES: readonly RuntimeDerivedCapability[];
+export declare function deriveRuntimeCapabilities(facts: SessionCapabilityFacts): string[];
+export declare function resolveSessionCapabilities(hostSupplied: readonly string[] | undefined, facts: SessionCapabilityFacts): string[];
+export declare function isBareDenied(canonicalName: string, disallowedTools: readonly string[] | undefined): boolean;
+export declare function buildAdvertisedSet(cfg: AdvertisedSetInputs): ToolDescriptor[];
+export interface EngineToolCall {
+    id: string;
+    name: string;
+    input: unknown;
+}
+export interface EngineToolResult {
+    output: string;
+    /**
+     * Spawn-surface parity (R-S4, research gap 6): the executor's own `isError`, carried to the engine
+     * so the model-facing `tool_result` block says `is_error: true` -- claude's shape for every tool
+     * error. Dropped here before, so every executor error reached the wire (and the daemon) as a
+     * success.
+     */
+    isError?: boolean;
+}
+export interface EngineFacingToolExecutor {
+    /** Phase 6 Task 3 (R6-6): `opts.signal` is the engine's per-turn abort. It reaches a real executor as `ToolExecutionContext.signal`. */
+    execute(call: EngineToolCall, opts?: ToolCallExecuteOptions): Promise<EngineToolResult>;
+}
+export interface RegistryToolExecutorDeps {
+    sessionId: string;
+    home: string;
+    /** Phase 5 fix wave, I1: the resolved winter root -- see `ToolExecutionContext.winterHome`. */
+    winterHome?: string;
+    /** WS-21 fix round 1, item 4: the shared store home -- see `ToolExecutionContext.storeHome`. */
+    storeHome?: string;
+    /** WS-21 §6.3 item 1, fix round 2: plugin workflow directories -- see `ToolExecutionContext.pluginWorkflows`. */
+    pluginWorkflows?: readonly {
+        name: string;
+        workflowsPath?: string;
+        workflowsPaths?: readonly string[];
+    }[];
+    /** SV-5 fix round 3 (I-4): the session's resolved settingSources -- see `ToolExecutionContext.settingSources`. */
+    settingSources?: readonly SettingSource[];
+    /** P7a (D19): the session's resolved brand -- see `ToolExecutionContext.brand`. */
+    brand?: BrandProfile;
+    getCwd: () => string;
+    probeReadAccess: (filePath: string) => ReadAccessProbe;
+    emitFrame: (frame: BackgroundTaskMessage) => void;
+    emitToolReference?: (names: string[]) => void;
+    session: ToolExecutionContext["session"];
+    readState: SessionReadState;
+    getTempDir: () => string;
+    sandboxSettings: SandboxSettings;
+    outDir?: string;
+    insideSubagent?: boolean;
+    isolationPinnedCwd?: boolean;
+    trustedWorkspace?: boolean;
+    agentId?: string;
+    agents?: Readonly<Record<string, unknown>>;
+    env?: Readonly<Record<string, string | undefined>>;
+    forkSubagentEnabled?: boolean;
+    backgroundByDefault?: boolean;
+    insideFork?: boolean;
+    advertisedToolNames?: () => readonly string[];
+    onAgentDefinitionRejected?: (rejection: {
+        source: "user" | "project" | "plugin";
+        filePath: string;
+        reason: string;
+    }) => void;
+    agentAvailability?: () => {
+        availableNames: readonly string[];
+        unavailableMessage: (agentType: string) => string | undefined;
+    };
+    getAvailabilityInputs?: () => AdvertisedSetInputs;
+}
+export declare function buildRegistryToolExecutor(deps: RegistryToolExecutorDeps): EngineFacingToolExecutor;
+export declare function buildRegistryToolExecutorWithFallback(deps: RegistryToolExecutorDeps, fallback: EngineFacingToolExecutor): EngineFacingToolExecutor;

package/dist/tools/task-graph-store.d.ts

@@ -0,0 +1,61 @@
+export type TaskStatus = "pending" | "in_progress" | "completed" | "deleted";
+export interface TaskGraphRow {
+    id: string;
+    subject: string;
+    description: string;
+    activeForm?: string;
+    status: TaskStatus;
+    blocks: string[];
+    blockedBy: string[];
+    owner?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface TaskCreateInput {
+    subject: string;
+    description: string;
+    activeForm?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface TaskUpdateInput {
+    taskId: string;
+    subject?: string;
+    description?: string;
+    activeForm?: string;
+    status?: TaskStatus;
+    addBlocks?: string[];
+    addBlockedBy?: string[];
+    owner?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface TaskListRow {
+    id: string;
+    subject: string;
+    status: TaskStatus;
+    owner?: string;
+    blockedBy: string[];
+}
+export type TaskUpdateError = {
+    kind: "not_found";
+    taskId: string;
+} | {
+    kind: "self_reference";
+    taskId: string;
+    field: "addBlocks" | "addBlockedBy";
+} | {
+    kind: "unknown_reference";
+    taskId: string;
+    field: "addBlocks" | "addBlockedBy";
+    missing: string;
+};
+export type TaskUpdateResult = {
+    ok: true;
+    row: TaskGraphRow;
+} | {
+    ok: false;
+    error: TaskUpdateError;
+};
+export declare function resetTaskGraphStoreForTest(sessionId?: string): void;
+export declare function createTask(sessionId: string, input: TaskCreateInput): TaskGraphRow;
+export declare function getTask(sessionId: string, taskId: string): TaskGraphRow | undefined;
+export declare function listTasks(sessionId: string): TaskListRow[];
+export declare function updateTask(sessionId: string, input: TaskUpdateInput): TaskUpdateResult;

package/dist/toolsearch/aliases.d.ts

@@ -0,0 +1,26 @@
+import { type AdvertisedPartition } from "../tools/registry.js";
+import { type BrandProfile } from "@yanlinglabs/winter-agent-sdk";
+/** The one brand field this module needs: the standing server's name. */
+export type AliasBrand = Pick<BrandProfile, "mcpServerName">;
+export declare const WINTER_CANONICAL_ALIAS_SUFFIXES: Readonly<Record<string, string>>;
+/** The branch's own canonical pair for a given brand. */
+export declare function canonicalAliases(brand?: AliasBrand): Record<string, string>;
+/** The default profile's pair, for every caller that has not threaded a brand. */
+export declare const WINTER_CANONICAL_ALIASES: Readonly<Record<string, string>>;
+export declare function effectiveAliasTable(hostAliases: Record<string, string> | undefined, brand?: AliasBrand): Record<string, string>;
+export declare function resolveToolAlias(name: string, toolAliases: Record<string, string> | undefined): string;
+export declare function suppressAliasedDuplicates(partition: AdvertisedPartition, toolAliases: Record<string, string> | undefined, disallowedTools?: readonly string[], brand?: AliasBrand): AdvertisedPartition;
+export interface AliasExclusion {
+    reason: string;
+    cause: "native-excluded" | "target-denied";
+}
+export declare function aliasExclusionReasons(partition: AdvertisedPartition, hostAliases: Record<string, string> | undefined, disallowedTools: readonly string[] | undefined, brand?: AliasBrand): Map<string, AliasExclusion>;
+export declare function hideAliasExcludedTwins(partition: AdvertisedPartition, hostAliases: Record<string, string> | undefined, disallowedTools: readonly string[] | undefined, brand?: AliasBrand): AdvertisedPartition;
+export declare function aliasPermissionIdentities(name: string, hostAliases: Record<string, string> | undefined, brand?: AliasBrand): string[];
+export interface AliasIdentityProbes {
+    deniedByRule(name: string): boolean;
+    askedByRule(name: string): boolean;
+    hookScoped(name: string): boolean;
+    allowedByRule(name: string): boolean;
+}
+export declare function resolvePermissionIdentity(name: string, hostAliases: Record<string, string> | undefined, probes: AliasIdentityProbes, brand?: AliasBrand): string;

package/dist/toolsearch/exposure.d.ts

@@ -0,0 +1,30 @@
+import { type DeferralActivation, type ToolDescriptor } from "../tools/registry.js";
+import type { PermissionMode } from "@yanlinglabs/winter-agent-sdk";
+export interface ExposureQuery {
+    mode: PermissionMode;
+    activation: DeferralActivation;
+    platform?: NodeJS.Platform;
+    capabilities?: readonly string[];
+    disallowedTools?: readonly string[];
+    insideSubagent?: boolean;
+    familyMetadata?: {
+        taskNative?: boolean;
+    };
+    toolAliases?: Record<string, string>;
+    /**
+     * Fix round 21: the run's own scope over the process-wide registry -- engine.ts passes the SAME
+     * predicate its advertised partition applies (`computeAdvertisedPartition`: a live server's MCP tool
+     * only for a server the run can see), so ToolSearch never finds or selects another run's tools
+     * (e.g. a subagent's own object-form server's, while that subagent runs). claude's ToolSearch
+     * searches only the calling agent's own tools (`x = refreshTools?.() ?? tools`, dump byte
+     * 15619044). Absent = no scope (every pre-round-21 caller).
+     */
+    toolFilter?: (descriptor: ToolDescriptor) => boolean;
+}
+export interface DeferredCandidates {
+    eager: readonly ToolDescriptor[];
+    deferred: readonly ToolDescriptor[];
+    hidden: readonly ToolDescriptor[];
+    totalDeferredTools: number;
+}
+export declare function computeExposurePartition(query: ExposureQuery): DeferredCandidates;

package/dist/toolsearch/ranking.d.ts

@@ -0,0 +1,6 @@
+export interface RankableCandidate {
+    name: string;
+    description: string;
+    searchHint?: string;
+}
+export declare function rankCandidates(query: string, candidates: readonly RankableCandidate[], maxResults: number): string[];

package/dist/toolsearch/search.d.ts

@@ -0,0 +1,45 @@
+import type { PermissionMode } from "@yanlinglabs/winter-agent-sdk";
+import type { DeferralActivation, ToolDescriptor } from "../tools/registry.js";
+import type { McpServerStateSource } from "../mcp/state.js";
+export interface FailedMcpServerEntry {
+    name: string;
+    errorCode?: string;
+    error?: string;
+}
+export interface ToolSearchResult {
+    matches: string[];
+    query: string;
+    total_deferred_tools: number;
+    pending_mcp_servers?: string[];
+    failed_mcp_servers?: FailedMcpServerEntry[];
+}
+export type ToolSearchOutcome = {
+    ok: true;
+    result: ToolSearchResult;
+} | {
+    ok: false;
+    message: string;
+};
+export interface ToolSearchDeps {
+    getMode(): PermissionMode;
+    activation: DeferralActivation;
+    platform?: NodeJS.Platform;
+    capabilities?: readonly string[];
+    disallowedTools?: readonly string[];
+    insideSubagent?: boolean;
+    familyMetadata?: {
+        taskNative?: boolean;
+    };
+    stateSource?: McpServerStateSource;
+    toolAliases?: Record<string, string>;
+    toolFilter?: (descriptor: ToolDescriptor) => boolean;
+    emitToolReference?(names: string[]): void;
+    pendingWaitMs?: number;
+}
+declare function parseSelect(query: string): string[] | undefined;
+export declare function executeToolSearch(input: unknown, deps: ToolSearchDeps): Promise<ToolSearchOutcome>;
+export type ToolSearchSessionRuntime = Omit<ToolSearchDeps, "emitToolReference">;
+export declare function registerToolSearchSessionRuntime(sessionId: string, runtime: ToolSearchSessionRuntime): () => void;
+export declare function unregisterToolSearchSessionRuntime(sessionId: string): void;
+export declare function getToolSearchSessionRuntime(sessionId: string): ToolSearchSessionRuntime | undefined;
+export { parseSelect as parseToolSearchSelect };

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const RUNTIME_VERSION = "0.0.27";

package/dist/version.js

@@ -0,0 +1,5 @@
+// src/version.ts
+var RUNTIME_VERSION = "0.0.27";
+export {
+  RUNTIME_VERSION
+};

package/dist/web/fetchable-url.d.ts

@@ -0,0 +1,28 @@
+/** claude's fetch-time rejects, as a reason a caller may name in a comment or a test. The TEXT the model sees is always `FETCH_TIME_INVALID_URL`. */
+export type UnfetchableUrlReason = "too-long" | "embedded-credentials" | "single-label-hostname";
+/** The three FETCH-TIME rejects' text: a bare `Invalid URL`, never the fuller parse-failure sentence (extraction-notes fidelity #2, corrected). */
+export declare const FETCH_TIME_INVALID_URL = "Invalid URL";
+/** The `http:` -> `https:` upgrade, unconditional and claude's own. Returns `url` itself for any other scheme. */
+export declare function upgradeToHttps(url: URL): URL;
+/**
+ * claude's own fetch-time rejects for ONE already-parsed URL: overlong, embedded credentials, a
+ * hostname with fewer than two dot-separated labels. `undefined` means none of them applies.
+ *
+ * Run PER HOP by the executor (claude runs it once on the raw input; running it again on every
+ * upgraded hop is strictly stricter and is kept deliberately -- a disclosed, safe deviation).
+ */
+export declare function fetchTimeUrlRefusal(url: URL): UnfetchableUrlReason | undefined;
+/**
+ * Is this target one the executor is CERTAIN to refuse before it touches the network -- i.e. after
+ * the https upgrade, does a fetch-time reject apply?
+ *
+ * The question the permission layer asks. It takes an already-parsed URL, so an UNPARSEABLE input is
+ * outside this predicate entirely: such a call names no host, so no rule could be suggested or saved
+ * for it, and its own refusal (`validateInput`'s parse-failure sentence) is a different text.
+ */
+export declare function isCertainlyUnfetchableUrl(url: URL): UnfetchableUrlReason | undefined;
+/**
+ * The one sentence every text about a private/loopback target ends with, so the ask, the rule hint
+ * and the executor's own refusal all say the SAME true thing about what an approval can achieve.
+ */
+export declare const FETCHABLE_TARGET_SHAPE = "WebFetch upgrades http to https unconditionally, so only an https service at an IPv4 literal (127.0.0.1) or at a name with two or more dot-separated labels (printer.local) is reachable at all -- a plain-http port on localhost or an IPv6 literal cannot be fetched whatever the policy says.";