/** What a model is FOR — a single axis, orthogonal to size (size is conveyed
 *  by `params` / `sizeBytes`). Lets the CLI group + filter without parsing the
 *  description. */
export type ModelCategory = "general" | "coding" | "reasoning" | "embedding";
export type ModelInfo = {
    /** Hugging Face URI passed to `node-llama-cpp`'s `resolveModelFile`. */
    uri: string;
    /** Human-readable parameter count, e.g. "1.7B" or "70B". */
    params: string;
    /** Approximate Q4_K_M download size in bytes. */
    sizeBytes: number;
    /** What the model is for (orthogonal to size). */
    category: ModelCategory;
    /** One-line "what is it good for" — shown by `agency local alias list`. */
    description: string;
    /** Native context window in tokens. */
    contextWindow: number;
    /** License identifier (SPDX-ish). Curated entries are permissive only
     *  (apache-2.0 / mit); restrictively-licensed models (older Gemma's custom
     *  terms, llama) are intentionally excluded. Gemma 4 ships under apache-2.0,
     *  so it qualifies; Gemma 1–3 did not. */
    license: string;
    /** Pinned content SHA-256 (hex) of the resolved single-file GGUF, used to
     *  verify the download. Absent for sharded models (see issue #348). */
    sha256?: string;
};
/** Curated short-name → ModelInfo catalog. Permissive licenses only
 *  (apache-2.0 / mit). Ordered roughly by size within each grouping. */
export declare const CURATED_LOCAL_MODELS: Record<string, ModelInfo>;
/** Where downloaded models live, in precedence order:
 *   1. `AGENCY_MODELS_DIR` env var (per-machine override).
 *   2. `client.modelsDir` in the nearest `agency.json` (read at runtime, like
 *      `modelAliases`), so the CLI and the agent share one configurable dir.
 *   3. `~/.agency-agent/models` (the default; shared with the agent so a CLI
 *      `agency local download` pre-populates what `agency agent --local-model`
 *      reuses). */
export declare function defaultCacheDir(): string;
/** The agency.json that owns aliases: nearest `agency.json` walking up from
 *  `startDir` (cwd by default); falls back to `~/agency.json` when none is
 *  found. Exported so the CLI can echo it on every write. */
export declare function resolveAliasConfigPath(startDir?: string): string;
/** A model alias value: either the bare URI (hand-edit shorthand) or an
 *  object carrying the URI plus optional display metadata. `source: "remote"`
 *  marks an entry written by `agency local refresh` (see `_refreshCatalog`);
 *  hand-added aliases have no `source`. */
export type AliasObject = {
    uri: string;
    source?: "remote";
    params?: string;
    sizeBytes?: number;
    category?: ModelCategory;
    contextWindow?: number;
    license?: string;
    description?: string;
    sha256?: string;
};
export type AliasValue = string | AliasObject;
/** The URI an alias points at, regardless of string/object form. */
export declare function aliasUri(value: AliasValue): string;
export declare function readModelAliases(file?: string): Record<string, AliasValue>;
/** Entry returned by `_listModelNames`. */
export type ModelNameEntry = {
    name: string;
    target: string;
    source: "curated" | "alias";
    params?: string;
    sizeBytes?: number;
    category?: ModelCategory;
    description?: string;
    contextWindow?: number;
    license?: string;
    sha256?: string;
};
export declare function _resolveModelName(value: string, file?: string): string;
export declare function _listModelNames(file?: string): ModelNameEntry[];
export declare function _aliasModel(name: string, uri: string, file?: string): string;
/** Outcome of `_unaliasModel`. `removed` distinguishes the actual mutation
 *  (true) from the "alias / file wasn't there, file untouched" no-op (false),
 *  so the CLI can print an accurate message instead of always saying
 *  "Removed alias …" even when nothing changed. */
export type UnaliasResult = {
    file: string;
    removed: boolean;
};
/** Remove an alias. Bails early (no write) if file or alias missing. */
export declare function _unaliasModel(name: string, file?: string): UnaliasResult;
export declare function _listDownloadedModels(cacheDir?: string): {
    name: string;
    path: string;
    sizeBytes: number;
}[];
export declare function _removeModel(name: string, cacheDir?: string): boolean;
export declare const DEFAULT_CATALOG_URL = "https://raw.githubusercontent.com/egonSchiele/agency-lang/main/packages/agency-lang/data/model-catalog.json";
/** A validated entry from the remote catalog. Mirrors `AliasObject` minus the
 *  `source` tag (which `_refreshCatalog` adds on write). */
export type CatalogModel = {
    uri: string;
    params?: string;
    sizeBytes?: number;
    category?: ModelCategory;
    contextWindow?: number;
    license?: string;
    description?: string;
    sha256?: string;
};
/** Resolve the catalog URL: explicit arg → env → config → built-in default. */
export declare function resolveCatalogUrl(explicit?: string, file?: string): string;
/** Parse + validate the catalog JSON. Throws on blob-level problems (bad JSON,
 *  unsupported version, `models` not an object) so refresh aborts without
 *  touching agency.json. Skips an individual entry (with a warning) when its
 *  `uri` is missing/invalid; metadata fields with the wrong type are dropped
 *  but the entry is kept. */
export declare function parseCatalog(text: string): Record<string, CatalogModel>;
/** Default fetcher: a local file path / `file://` URL is read from disk;
 *  otherwise an HTTPS-only GET with a bounded timeout and a streamed byte cap.
 *  `http:` (and other non-https URL schemes) are rejected. */
export declare function fetchCatalog(url: string): Promise<string>;
export type SkippedAlias = {
    name: string;
    keptUri: string;
    remoteUri: string;
};
export type RefreshResult = {
    url: string;
    file: string;
    added: string[];
    updated: string[];
    unchanged: string[];
    removed: string[];
    skipped: SkippedAlias[];
    modelCount: number;
};
/** Fetch + validate the catalog, then rewrite the `source:"remote"` aliases in
 *  agency.json from it. User-owned aliases are preserved and win on name
 *  collisions (the remote entry is skipped). Throws (leaving the file
 *  untouched) on fetch/parse/validation failure. */
export declare function _refreshCatalog(opts?: {
    url?: string;
    fetcher?: (url: string) => Promise<string>;
    file?: string;
}): Promise<RefreshResult>;
/** Discover global `node_modules` roots reported by `npm` and `pnpm`, in that
 *  order. Each entry is the directory printed by `<tool> root -g` (which is
 *  itself a `node_modules` dir, e.g. `/opt/homebrew/lib/node_modules` for
 *  Homebrew npm, `~/Library/pnpm/global/5/node_modules` for pnpm). Failures
 *  (tool not installed, exit non-zero, dir missing) are silently skipped. */
export declare function globalNodeModulesRoots(): string[];
/** Try to resolve `smoltalk-llama-cpp` from the given global `node_modules`
 *  roots. Each `root` is itself a `node_modules` directory (the convention
 *  `npm root -g` / `pnpm root -g` uses). Node's resolver looks for
 *  `<parent>/node_modules/<pkg>` for each parent dir it walks up, so the
 *  createRequire base must live in the root's PARENT directory — from
 *  `<root>/../_resolver.js` it correctly finds `<root>/smoltalk-llama-cpp/...`.
 *  Exported for unit-testing with a controllable list of roots. */
export declare function resolveSmoltalkLlamaCppFromRoots(roots: string[]): string | null;
/** Resolve `smoltalk-llama-cpp` to the absolute path of its main entry,
 *  searching:
 *   1. The local `require` paths walking up from this file (covers in-workspace
 *      `pnpm add` and a user-project install).
 *   2. Each global `node_modules` root reported by `npm root -g` / `pnpm root -g`
 *      (covers `npm i -g` and `pnpm add -g` — the documented install methods).
 *
 *  Returns `null` if the package isn't reachable from any of those. */
export declare function resolveSmoltalkLlamaCppEntry(): string | null;
/** True if smoltalk-llama-cpp is reachable from the local require paths OR
 *  from a global node_modules root (npm or pnpm). */
export declare function _localModelsSupported(): boolean;
/** Whether the local-model commands should be allowed to run. True when
 *  smoltalk-llama-cpp is installed OR the caller has supplied their own
 *  provider module via AGENCY_LLAMA_PROVIDER_MODULE. Mirrors the gate inside
 *  `requireSupport()`; used by the CLI so `agency local download/list/remove`
 *  works in the override scenario (otherwise the CLI would exit 1 even though
 *  the underlying TS functions would happily run). */
export declare function hasLocalModelSupport(): boolean;
/** Register the llama-cpp provider into agency's own smoltalk. */
export declare function _registerLocalProvider(): Promise<void>;
/** Stream-hash a file's SHA-256 (hex), never buffering the whole file. The
 *  `update` is guarded so a synchronous throw in the data handler rejects the
 *  promise instead of escaping it. */
export declare function fileSha256(filePath: string): Promise<string>;
/** Verify `filePath` against the expected hex SHA-256. On mismatch, rename the
 *  file to `<filePath>.invalidSha` (kept for inspection; won't be picked up, so
 *  the next run re-downloads) and throw. A failed rename is logged (not
 *  swallowed) and reflected in the thrown message. */
export declare function verifyModelFile(filePath: string, expected: string, name: string): Promise<void>;
/** The pinned SHA-256 for a model name/alias, or undefined when none is known
 *  (raw uri/path, string alias, alias/curated without a hash, or a sharded
 *  model). An alias entry governs the name entirely — a user alias shadowing a
 *  curated name must NOT borrow the curated hash, but a user MAY opt in by
 *  setting their own `sha256` on the alias object. */
export declare function pinnedSha256(value: string, file?: string): string | undefined;
/** Was the resolved file freshly downloaded (not already cached)? */
export type FreshnessProbe = (resolved: string) => boolean;
/** Snapshot the cache dir, returning a probe that reports whether a resolved
 *  path is newly downloaded. node-llama-cpp stores models FLAT in `dir` with a
 *  prefixed filename — no per-repo subdirs (verified against its
 *  `buildHuggingFaceFilePrefix`) — so matching by basename is correct. */
export declare function snapshotFreshness(dir: string): FreshnessProbe;
/** Resolve a name/uri/path to a local .gguf path, downloading if needed. */
export declare function _downloadModel(value: string, cacheDir?: string): Promise<string>;
/** Convenience: register the provider + ensure the model is downloaded. */
export declare function _registerLocalModel(value: string, cacheDir?: string): Promise<string>;
export declare function formatGB(bytes: number): string;
/** Context window in compact units: 8192 → "8K", 131072 → "128K", 1e7 → "10M". */
export declare function formatCtx(tokens: number): string;
/** Render the usable-model list as an aligned table: a header row plus one
 *  fact row per curated model (params, category, size, context window,
 *  license), the description on a dimmed line below, a blank line between
 *  models. User aliases (which carry no metadata) follow in an ALIASES
 *  section as `name → target`. Returns the block as a string with no trailing
 *  newline (the caller's `console.log` adds exactly one). */
export declare function formatModelCatalog(): string;
/** Print the model catalog to stdout. The agent's bare `--local-model`
 *  path calls this through `std::agency/local`. */
export declare function _printLocalCatalog(): void;