@sayknow-cli/coding-agent 0.4.7 → 0.5.1

package/CHANGELOG.md

@@ -5,6 +5,128 @@ This file tracks the **fork's own releases**; upstream's full feature history li
 in that project. Each release notes the upstream version it is built on.
 
 
+## [0.5.1] — 2026-07-29
+
+Built on upstream **gajae-code v0.12.0**.
+
+### Fixed (Sayknow Pet still left sixel residue under tmux)
+
+0.5.0 gave tmux ownership of the pet's sixel, which is the real fix — but it only
+takes effect for a client that attaches *after* the feature is set, because tmux
+computes client features at attach time. Every already-attached client kept
+falling back to DCS passthrough, and that fallback still erased at tmux level
+while its pixels lived in the outer terminal. So the residue persisted for
+exactly the people who already had a session open.
+
+- **The erase now rides the same envelope as the draw.** When the frame goes out
+  through passthrough, the erase does too, reaching the terminal that actually
+  holds the image; the absolute coordinates match because the draw used the same
+  ones. When tmux owns the sixel, the erase stays at tmux level as before.
+- **`terminal-features` is set with the correct scope.** It is a *server* option,
+  so the previous `set-option -aq -t <target>` silently ignored the target. Now
+  `set-option -saq`.
+- Added a regression test that pins the multiplexer environment and asserts draw
+  and erase share one envelope. The pet suite previously inherited whatever
+  terminal the developer ran it in, so it passed on CI and failed inside tmux;
+  the environment is now pinned per test.
+
+## [0.5.0] — 2026-07-28
+
+Built on upstream **gajae-code v0.12.0** (previous fork release tracked v0.11.6).
+
+### Security (inherited from upstream v0.12.0)
+
+Every path below trusted the caller's `cwd/.env`, so **opening a hostile repository
+was enough** to trigger it. All now resolve through the non-project resolver
+(launching shell plus SKC/user-owned files); shell and user configuration are
+unchanged.
+
+- **Provider base URLs** — `<PROVIDER>_BASE_URL` is derived generically, so a planted
+  `.env` could redirect authenticated traffic for *every* provider.
+- **Browser launch overrides** — could pick the browser binary, route all traffic
+  through an attacker proxy, and disable certificate validation.
+- **Spawned command overrides** (`SKC_SDK_SESSION_COMMAND`,
+  `SKC_HARNESS_PROCESS_START_COMMAND`) — chose which binary those paths execute.
+- **Smithery origin / API base / API key** — the auth session the user is sent to,
+  and the credential sent with every call.
+- **Native skill hook config dirs** — could point the hook at a directory the repo
+  ships and inject its own `skills.customDirectories`, bypassing escalation guards.
+
+Also: **memory consolidation now redacts GitHub tokens.** The scrubber covered AWS
+ids, JWTs, and keyword-prefixed keys, but `ghp_` / `gho_` / `github_pat_` carry none
+of those markers, so a token reached `MEMORY.md` and `memory_summary.md` verbatim —
+and that summary is injected into every later session.
+
+### Changed (upstream replaced two surfaces the fork had ported)
+
+- The typed deep-interview **draft** CLI was reverted upstream and replaced with a
+  staged-transition surface (`stage --for <transition> --input '<json>'`, `check`,
+  `apply`, `discard`; one pending draft per session, no `--draft-id`). The fork
+  follows upstream here rather than keeping a surface upstream retired.
+- The fork's `absoluteClear` multiplexer width-reflow repair is superseded by
+  upstream's width-settle repair, which runs once per settled width sequence
+  instead of once per SIGWINCH. Upstream's implementation is kept.
+
+### Fixed (Sayknow Pet leaves sixel residue under tmux)
+
+- **Give tmux ownership of the pet's sixel instead of smuggling it past tmux.**
+  The pet was drawn with DCS passthrough, which writes pixels straight into the
+  outer terminal's image plane, while the erase was an `ECH` that only ever
+  reached tmux's cell buffer. tmux never recorded the image, so nothing could
+  remove it — every frame stacked another vertical band above the pet.
+
+  This is the same root cause behind the oversize/frozen animation (0.4.6) and
+  the viewport scroll (0.4.7): tmux's screen model and the real screen disagreed.
+  Those releases each patched the *draw* path; the *erase* path was never
+  revisited, so the residue survived all three fixes.
+
+  SKC-launched sessions now append `terminal-features ,*:sixel`, and the widget
+  sends the frame directly whenever tmux claims sixel. tmux 3.4+ parses it into
+  its own screen model (`screen_write_sixelimage`) and re-renders it, so the
+  existing erase actually deletes the image and scroll/resize/copy-mode stay
+  consistent. Passthrough remains only as the fallback for terminals or tmux
+  builds that do not claim sixel.
+
+### Fixed (rebrand leakage)
+
+- **Stop creating `.gjc-*` paths.** `recovery_fs` and `path_identity` still wrote
+  `.gjc-recovery`, `.gjc-managed-remove-*`, and `.gjc-exact-unlink-*` on disk: the
+  rename never reached them, so recovery state landed under an upstream-branded
+  directory name. 24 residual tokens are gone and the sync pipeline now fails the
+  build instead of shipping them.
+
+### Fixed (fork pipeline)
+
+The fork layer is regenerated as `gen-tree(upstream tag) = codemod + deletions +
+overlay + patches + identity`. Five defects made that identity false:
+
+- **Overlay swallowed upstream changes.** 66 upstream-owned files were carried as
+  whole-file overlays, so every upstream edit to them was silently discarded —
+  including `packages/tui`'s `node-pty` dependency. Ownership is now decided by
+  the base tree: present upstream ⇒ patch, absent ⇒ overlay (45 → 134 patches).
+- **Release versions leaked into patch context.** A version bump invalidated the
+  context lines of unrelated hunks, so patches rejected on every release. Version
+  text is now neutralized on both sides of extraction and restored by the identity
+  stamp.
+- **Deletions were unrepresentable.** Upstream files the fork drops (`crates/skc-sdk`
+  and others) reappeared on each sync; they are now declared and replayed.
+- **Binary assets were declared as patches**, producing unappliable
+  "Binary files differ" stubs. They are demoted to overlay automatically.
+- **The codemod never converged.** Overlay and patch payloads carry upstream text
+  that the single first pass cannot see, so the idempotence gate could not pass.
+
+`gen-tree` also refuses to run against the fork repo itself — an empty argument
+previously codemodded and version-stamped the working tree in place.
+
+### Added (ported from upstream)
+
+- `ServerHandle::push_frame_and_wait` in `skc-notifications`, so the SDK can await
+  per-connection delivery receipts instead of fire-and-forget broadcast.
+- `Process.signalRoot` napi binding for pinned single-process signalling.
+- Worker integration attempts accept an `AbortSignal` and bail between git probes.
+- The deep-interview staged-transition surface (`stage`, `check`, `apply`, `discard`,
+  `initialize-context`, `confirm-topology`).
+
 ## [0.4.7] — 2026-07-24
 
 ### Fixed (Sayknow Pet scroll under tmux)

package/dist/types/capability/index.d.ts

@@ -17,26 +17,16 @@ export declare function loadCapability<T>(capabilityId: string, options?: LoadOp
  * Call this once on startup to enable persistent provider state.
  */
 export declare function initializeWithSettings(activeSettings: Settings): void;
-/**
- * Disable a provider globally (across all capabilities).
- */
-export declare function disableProvider(providerId: string): void;
-/**
- * Enable a previously disabled provider.
- */
-export declare function enableProvider(providerId: string): void;
-/**
- * Check if a provider is enabled.
- */
-export declare function isProviderEnabled(providerId: string): boolean;
-/**
- * Get list of all disabled provider IDs.
- */
-export declare function getDisabledProviders(): string[];
-/**
- * Set disabled providers from a list (replaces current set).
- */
-export declare function setDisabledProviders(providerIds: string[]): void;
+/** Disable a provider for the supplied session settings. */
+export declare function disableProvider(providerId: string, activeSettings?: Settings): void;
+/** Enable a provider for the supplied session settings. */
+export declare function enableProvider(providerId: string, activeSettings?: Settings): void;
+/** Check whether a provider is enabled by the supplied session settings. */
+export declare function isProviderEnabled(providerId: string, activeSettings?: Settings | undefined): boolean;
+/** Get disabled providers from the supplied session settings. */
+export declare function getDisabledProviders(activeSettings?: Settings | undefined): string[];
+/** Replace disabled providers for the supplied session settings. */
+export declare function setDisabledProviders(providerIds: string[], activeSettings?: Settings): void;
 /**
  * Get a capability definition (for introspection).
  */

package/dist/types/capability/types.d.ts

@@ -5,6 +5,7 @@
  * paths like `.skc`, `.gemini`, or `.vscode`, they simply ask for `load("mcps")`
  * and get back a unified array of MCP servers.
  */
+import type { Settings } from "../config/settings";
 /**
  * Context passed to every provider loader.
  */
@@ -64,6 +65,8 @@ export interface LoadOptions {
     includeDisabled?: boolean;
     /** Explicit disabled extension IDs to apply instead of settings. */
     disabledExtensions?: string[];
+    /** Session settings whose provider policy applies to this load. */
+    settings?: Settings;
 }
 /**
  * Source metadata attached to every loaded item.

package/dist/types/cli/args.d.ts

@@ -52,5 +52,3 @@ export interface Args {
     authBootstrap?: true;
 }
 export declare function parseArgs(args: string[]): Args;
-export declare function getExtraHelpText(): string;
-export declare function printHelp(): void;

package/dist/types/cli/read-cli.d.ts

@@ -1,4 +1,5 @@
 export interface ReadCommandArgs {
     path: string;
+    truncation?: "head" | "last" | "both";
 }
 export declare function runReadCommand(cmd: ReadCommandArgs): Promise<void>;

package/dist/types/cli.d.ts

@@ -6,6 +6,13 @@
 import "@sayknow-cli/utils/postmortem";
 import { Command, type CommandEntry } from "@sayknow-cli/utils/cli";
 export declare const commands: CommandEntry[];
+export declare function interactiveBootstrapText(argv: readonly string[], stdinIsTTY?: boolean, stdoutIsTTY?: boolean): string | undefined;
+type MemoryGuardNativeSmokeLoad = () => Record<string, unknown>;
+export declare function isMemoryGuardNativeSmokeFastPath(argv: readonly string[]): boolean;
+export declare function runMemoryGuardNativeSmokeFastPath(options?: {
+    loadNative?: MemoryGuardNativeSmokeLoad;
+    writeStdout?: (text: string) => void;
+}): void;
 export declare class RootHelpCommand extends Command {
     static description: string;
     static hidden: boolean;
@@ -98,7 +105,7 @@ export declare class RootHelpCommand extends Command {
         };
         thinking: import("@sayknow-cli/utils/cli").FlagDescriptor<"string"> & {
             description: string;
-            options: string[];
+            options: import("@sayknow-cli/ai").Effort[];
         };
         hook: import("@sayknow-cli/utils/cli").FlagDescriptor<"string"> & {
             description: string;
@@ -141,3 +148,4 @@ export declare function normalizeResumeAlias(argv: readonly string[]): string[];
 export declare function routeRootArgv(argv: readonly string[]): string[];
 /** Run the CLI with the given argv (no `process.argv` prefix). */
 export declare function runCli(argv: string[]): Promise<void>;
+export {};

package/dist/types/commands/daemon.d.ts

@@ -31,10 +31,10 @@ export default class Daemon extends Command {
         force: import("@sayknow-cli/utils/cli").FlagDescriptor<"boolean"> & {
             description: string;
         };
-        "graceful-timeout-ms": import("@sayknow-cli/utils/cli").FlagDescriptor<"integer"> & {
+        "graceful-timeout-ms": import("@sayknow-cli/utils/cli").FlagDescriptor<"string"> & {
             description: string;
         };
-        "kill-timeout-ms": import("@sayknow-cli/utils/cli").FlagDescriptor<"integer"> & {
+        "kill-timeout-ms": import("@sayknow-cli/utils/cli").FlagDescriptor<"string"> & {
             description: string;
         };
         "spawn-if-stopped": import("@sayknow-cli/utils/cli").FlagDescriptor<"boolean"> & {

package/dist/types/commands/deep-interview.d.ts

@@ -24,6 +24,15 @@ export default class DeepInterview extends Command {
         "session-id": import("@sayknow-cli/utils/cli").FlagDescriptor<"string"> & {
             description: string;
         };
+        input: import("@sayknow-cli/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
+        for: import("@sayknow-cli/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
+        reset: import("@sayknow-cli/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
         write: import("@sayknow-cli/utils/cli").FlagDescriptor<"boolean"> & {
             description: string;
         };

package/dist/types/commands/harness.d.ts

@@ -1,4 +1,25 @@
 import { Command } from "@sayknow-cli/utils/cli";
+/**
+ * Operator override for the process-start probe command, resolved from trusted
+ * environment sources only.
+ *
+ * The result is spawned, so whatever can set it chooses which binary runs.
+ * `$env` merges the caller's `cwd/.env` into `process.env`, so reading it there
+ * would let repository content pick the command; resolve it the same way
+ * provider credentials are (launching shell plus SKC/user-owned `.env` files,
+ * never the project `.env`). A malformed override stays fatal rather than
+ * silently falling back to `ps`, matching the previous behavior.
+ */
+type ProcessStartCommandOverride = {
+    kind: "none";
+} | {
+    kind: "invalid";
+} | {
+    kind: "command";
+    command: string[];
+};
+/** Test seam: the process-start command override as resolved from trusted env. */
+export declare function processStartCommandOverrideForTest(): ProcessStartCommandOverride;
 export default class Harness extends Command {
     #private;
     static description: string;
@@ -41,3 +62,4 @@ export default class Harness extends Command {
     static examples: string[];
     run(): Promise<void>;
 }
+export {};

package/dist/types/commands/read.d.ts

@@ -10,6 +10,12 @@ export default class Read extends Command {
             required: true;
         };
     };
+    static flags: {
+        truncation: import("@sayknow-cli/utils/cli").FlagDescriptor<"string"> & {
+            options: string[];
+            description: string;
+        };
+    };
     static examples: string[];
     run(): Promise<void>;
 }

package/dist/types/commands/sdk.d.ts

@@ -15,17 +15,35 @@ export declare function runSessionHost(timing?: {
     cwd?: string;
     processIncarnation?: (pid: number) => string | undefined;
 }): Promise<void>;
+export type SdkInternalArgv = {
+    action: "broker-internal";
+    agentDir: string;
+} | {
+    action: "session-host-internal";
+};
+/** Parses the exact private argv contracts used by SDK child-process spawns. */
+export declare function parseSdkInternalArgv(argv: readonly string[]): SdkInternalArgv;
 export default class Sdk extends Command {
     static description: string;
     static hidden: boolean;
+    static delegateHelp: boolean;
     static args: {
         action: import("@sayknow-cli/utils/cli").ArgDescriptor & {
-            required: true;
+            required: false;
             options: string[];
         };
     };
     static flags: {
-        "agent-dir": import("@sayknow-cli/utils/cli").FlagDescriptor<"string"> & {
+        stdio: import("@sayknow-cli/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
+        socket: import("@sayknow-cli/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
+        session: import("@sayknow-cli/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
+        "pending-ceiling": import("@sayknow-cli/utils/cli").FlagDescriptor<"string"> & {
             description: string;
         };
     };

package/dist/types/config/keybindings.d.ts

@@ -151,7 +151,7 @@ export declare const KEYBINDINGS: {
     };
     readonly "app.session.fork": {
         readonly defaultKeys: [];
-        readonly description: "Fork session";
+        readonly description: "Branch from message";
     };
     readonly "app.session.resume": {
         readonly defaultKeys: [];
@@ -378,6 +378,10 @@ declare function migrateKeybindingsConfigFile(agentDir: string): void;
 export declare class KeybindingsManager extends TuiKeybindingsManager {
     #private;
     constructor(userBindings?: KeybindingsConfig, configPath?: string);
+    /**
+     * Replace user bindings only after canonical grammar validation.
+     */
+    setUserBindings(userBindings: KeybindingsConfig): void;
     /**
      * Create from config file at agentDir/keybindings.json.
      */
@@ -386,6 +390,11 @@ export declare class KeybindingsManager extends TuiKeybindingsManager {
      * Create an in-memory keybindings manager without file persistence.
      */
     static inMemory(userBindings?: KeybindingsConfig): KeybindingsManager;
+    /**
+     * Set the default display context used by composed surfaces that do not
+     * supply an explicit context.
+     */
+    setDisplayContext(context: KeyDisplayContext): void;
     /**
      * Reload keybindings from the config file.
      */
@@ -397,9 +406,30 @@ export declare class KeybindingsManager extends TuiKeybindingsManager {
     /**
      * Get display string for a keybinding (e.g., "ctrl+c/escape").
      */
-    getDisplayString(keybinding: Keybinding): string;
+    getDisplayString(keybinding: Keybinding, context?: KeyDisplayContext): string;
+    /**
+     * Get an accessibility-oriented display string for help surfaces.
+     * Darwin chords include both the concise glyphs and expanded key names.
+     */
+    getAccessibleDisplayString(keybinding: Keybinding, context?: KeyDisplayContext): string;
+    /**
+     * Format a fixed key chord using this manager's display context.
+     */
+    formatKeyHint(key: string): string;
+    /**
+     * Format a fixed key chord for accessibility-oriented help surfaces.
+     */
+    formatAccessibleKeyHint(key: string): string;
+}
+/**
+ * Key hint formatting utilities for UI labels.
+ */
+export interface KeyDisplayContext {
+    platform: NodeJS.Platform;
 }
-export declare function formatKeyHint(key: KeyId): string;
-export declare function formatKeyHints(keys: KeyId | KeyId[]): string;
+export declare function formatKeyHint(key: string, context?: KeyDisplayContext): string;
+export declare function formatAccessibleKeyHint(key: string, context?: KeyDisplayContext): string;
+export declare function formatKeyHints(keys: string | readonly string[], context?: KeyDisplayContext): string;
+export declare function formatAccessibleKeyHints(keys: string | readonly string[], context?: KeyDisplayContext): string;
 export type { Keybinding, KeybindingsConfig, KeyId };
 export { migrateKeybindingsConfigFile };

package/dist/types/config/model-profile-contract.d.ts

@@ -0,0 +1,40 @@
+import { type ModelProfileDefinition } from "./model-profiles";
+export declare const MODEL_PROFILE_DISCOVERY_QUERY = "models.profiles.list";
+export declare const MODEL_PROFILE_ERROR_DETAIL_MAX_BYTES = 2048;
+export interface ModelProfileCatalogItem {
+    id: string;
+    displayName: string;
+    source: "builtin" | "configured";
+    available?: boolean;
+}
+export interface UnknownModelProfileDetails {
+    requestedProfile: string;
+    availableProfiles: string[];
+    discoveryQuery: typeof MODEL_PROFILE_DISCOVERY_QUERY;
+}
+export interface ModelProfileRegistryErrorDetails {
+    requestedProfile?: string;
+    availableProfiles: [];
+    discoveryQuery: typeof MODEL_PROFILE_DISCOVERY_QUERY;
+}
+export type ModelProfileErrorDetails = UnknownModelProfileDetails | ModelProfileRegistryErrorDetails;
+export type ModelProfileErrorCode = "unknown_model_profile" | "model_profile_registry_error";
+export declare class UnknownModelProfileError extends Error {
+    readonly code: "unknown_model_profile";
+    readonly details: UnknownModelProfileDetails;
+    constructor(requestedProfile: string, profiles: ReadonlyMap<string, unknown>);
+}
+export declare class ModelProfileRegistryError extends Error {
+    readonly code: "model_profile_registry_error";
+    readonly details: ModelProfileRegistryErrorDetails;
+    constructor(requestedProfile?: string);
+}
+export declare function resolveModelProfileName(profileName: string, profiles: ReadonlyMap<string, unknown>): string;
+export declare function validateModelProfileName(profileName: string, profiles: ReadonlyMap<string, unknown>, registryError?: unknown): string;
+export declare function projectModelProfileCatalog(profiles: ReadonlyMap<string, ModelProfileDefinition>, registryError?: unknown): ModelProfileCatalogItem[];
+export declare function isModelProfileProviderAvailable(profile: ModelProfileDefinition, authenticatedProviders: ReadonlySet<string>): boolean;
+export declare function isModelProfileError(value: unknown): value is {
+    code: ModelProfileErrorCode;
+    message: string;
+    details: ModelProfileErrorDetails;
+};

package/dist/types/config/model-profiles.d.ts

@@ -1,7 +1,6 @@
-import type { SkcModelAssignmentTargetId } from "./model-registry";
 import { type ModelSelectorValue } from "./model-selector-value";
-import type { ModelsConfig } from "./models-config-schema";
-export type ModelProfileRole = SkcModelAssignmentTargetId;
+import type { ModelsConfig, SKC_MODEL_ASSIGNMENT_TARGET_IDS } from "./models-config-schema";
+export type ModelProfileRole = (typeof SKC_MODEL_ASSIGNMENT_TARGET_IDS)[number];
 export interface ModelProfileDefinition {
     name: string;
     requiredProviders: string[];

package/dist/types/config/model-registry.d.ts

@@ -371,6 +371,10 @@ export declare class ModelRegistry {
      * as providers with stored credentials. See issue #993.
      */
     hasConfiguredAuth(model: Model<Api>): boolean;
+    /**
+     * Check whether auth is configured for a provider.
+     */
+    hasConfiguredProviderAuth(provider: string): boolean;
     getDiscoverableProviders(): string[];
     getProviderDiscoveryState(provider: string): ProviderDiscoveryState | undefined;
     /**
@@ -388,6 +392,7 @@ export declare class ModelRegistry {
      */
     getApiKey(model: Model<Api>, sessionId?: string, options?: {
         credentialSelector?: AuthCredentialSelector;
+        signal?: AbortSignal;
     }): Promise<string | undefined>;
     /**
      * Get API key for a provider (e.g., "openai").

package/dist/types/config/provider-auth-health.d.ts

@@ -0,0 +1,14 @@
+import type { AuthStorage } from "@sayknow-cli/ai/auth-storage";
+/**
+ * Most recent OAuth validation outcome per provider, used only as an ordering
+ * hint so `/model` can rank a provider whose stored credentials failed
+ * validation below one that is healthy, without re-running validation itself.
+ *
+ * Entries are scoped to the `AuthStorage` that produced them and to its
+ * credential generation, so any login, logout, import, or deletion discards the
+ * stale result instead of overriding current auth state.
+ */
+export type ProviderAuthHealth = "valid" | "invalid";
+export declare function recordProviderAuthHealth(authStorage: AuthStorage, providerId: string, health: ProviderAuthHealth): void;
+export declare function getProviderAuthHealth(authStorage: AuthStorage, providerId: string): ProviderAuthHealth | undefined;
+export declare function clearProviderAuthHealth(authStorage: AuthStorage): void;

package/dist/types/config/provider-ranking.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Shared provider ordering used by every provider-facing selector (`/login`,
+ * `/model`, `/provider`).
+ *
+ * Providers the user already has come first, then a curated list of well-known
+ * providers, then everything else alphabetically. This is the single source of
+ * truth for that order — surfaces must not keep their own famous-provider list.
+ */
+/**
+ * Auth/config state of a provider as seen by the calling surface.
+ *
+ * - `valid` — stored credentials that validated successfully.
+ * - `checking` — stored credentials whose async validation is still in flight.
+ *   Ranked with `valid` so rows do not reflow when validation resolves.
+ * - `configured` — no OAuth record, but the provider is present in the model
+ *   registry with a working API key (custom/API-compatible providers).
+ * - `invalid` — stored credentials that failed validation (problematic login).
+ * - `none` — nothing stored and nothing configured.
+ */
+export type ProviderAuthState = "valid" | "checking" | "configured" | "invalid" | "none";
+export declare const PROVIDER_RANK_TIER: {
+    readonly existing: 0;
+    readonly problematic: 1;
+    readonly famous: 2;
+    readonly other: 3;
+};
+export type ProviderRankTier = (typeof PROVIDER_RANK_TIER)[keyof typeof PROVIDER_RANK_TIER];
+/**
+ * Curated provider order for the famous tier. Regional and device variants sit
+ * immediately behind their primary so related entries stay grouped.
+ */
+export declare const FAMOUS_PROVIDER_ORDER: readonly string[];
+/** A provider as ranked by a surface. `label` is what the user sees. */
+export interface RankableProvider {
+    id: string;
+    label: string;
+    authState: ProviderAuthState;
+}
+/** A provider's position in the ordering: its tier plus its rank inside that tier. */
+export interface ProviderRank {
+    tier: ProviderRankTier;
+    intraTierRank: number;
+}
+/**
+ * The single ranking result for a provider. `intraTierRank` is the curated
+ * famous-list position, or `Number.MAX_SAFE_INTEGER` for providers that are not
+ * on the list and therefore order by display label.
+ */
+export declare function rankProvider(provider: RankableProvider): ProviderRank;
+export declare function providerRankTier(authState: ProviderAuthState, id: string): ProviderRankTier;
+/** Position within the famous list, or `undefined` for providers not on it. */
+export declare function famousProviderIndex(id: string): number | undefined;
+/**
+ * Total order over providers: tier, then famous-list position, then display
+ * label, then id. The trailing id comparison guarantees no ties.
+ */
+export declare function compareRankedProviders(left: RankableProvider, right: RankableProvider): number;
+/** Convenience wrapper returning a new array in ranked order. */
+export declare function sortRankedProviders<T extends RankableProvider>(providers: readonly T[]): T[];