agency-lang 0.14.0 → 0.15.0

package/dist/lib/cli/local.d.ts

@@ -1,9 +1,20 @@
-import { type RefreshResult } from "../stdlib/localModels.js";
-export declare function aliasList(file?: string): import("../stdlib/localModels.js").ModelNameEntry[];
+import { type ModelNameEntry, type RefreshResult } from "../stdlib/localModels.js";
+export declare function aliasList(file?: string): ModelNameEntry[];
 export declare function aliasAdd(name: string, uri: string, file?: string): string;
 export declare function aliasRemove(name: string, file?: string): string;
+/** Deliberately ungated: browsing the catalog needs no provider package
+ *  (only download/remove do), and the pre-install experience — see what is
+ *  available, then get told what to install — is the point. */
 export declare function runList(): void;
-export declare function runDownload(value: string): Promise<void>;
+export declare const CUSTOM_CHOICE = "__custom__";
+/** Picker rows for the no-argument `agency local download`. Metadata-less
+ *  aliases get a bare name; the trailing choice lets the user type an hf: URI
+ *  or .gguf path. */
+export declare function downloadChoices(entries: ModelNameEntry[]): {
+    title: string;
+    value: string;
+}[];
+export declare function runDownload(value?: string): Promise<void>;
 export declare function runRemove(name: string): void;
 export declare function runResolve(value: string): void;
 export declare function runAliasList(): void;

package/dist/lib/cli/local.js

@@ -1,4 +1,6 @@
-import { _resolveModelName, _downloadModel, _listDownloadedModels, _listModelNames, _aliasModel, _unaliasModel, _removeModel, hasLocalModelSupport, formatGB, formatModelCatalog, _refreshCatalog, } from "../stdlib/localModels.js";
+import prompts from "prompts";
+import { _resolveModelName, _downloadModel, _listDownloadedModels, _listModelNames, _modelsCacheDir, _aliasModel, _unaliasModel, _removeModel, hasLocalModelSupport, formatGB, formatModelCatalog, formatLocalList, _refreshCatalog, } from "../stdlib/localModels.js";
+import { readDownloadManifest } from "../stdlib/localModelManifest.js";
 import { ttyColor } from "../utils/termcolors.js";
 /** Install-gate for I/O commands. Honors the AGENCY_LLAMA_PROVIDER_MODULE
  *  override the same way `requireSupport()` in `localModels.ts` does — a
@@ -31,26 +33,72 @@ export function aliasRemove(name, file) {
     }
     return inspected;
 }
+/** Deliberately ungated: browsing the catalog needs no provider package
+ *  (only download/remove do), and the pre-install experience — see what is
+ *  available, then get told what to install — is the point. */
 export function runList() {
-    gate();
-    const models = _listDownloadedModels();
-    if (models.length === 0) {
-        console.log("No models downloaded.");
-        return;
-    }
-    for (const m of models) {
-        console.log(`${m.name}\t${formatGB(m.sizeBytes)}`);
-    }
-    const total = models.reduce((sum, m) => sum + m.sizeBytes, 0);
-    console.log(`Total: ${formatGB(total)}`);
+    const dir = _modelsCacheDir();
+    console.log(formatLocalList({
+        dir,
+        entries: _listModelNames(),
+        manifest: readDownloadManifest(dir),
+        files: _listDownloadedModels(),
+    }));
+}
+export const CUSTOM_CHOICE = "__custom__";
+/** Picker rows for the no-argument `agency local download`. Metadata-less
+ *  aliases get a bare name; the trailing choice lets the user type an hf: URI
+ *  or .gguf path. */
+export function downloadChoices(entries) {
+    const rows = entries.map((e) => ({
+        title: e.params !== undefined && e.sizeBytes !== undefined
+            ? `${e.name}  (${e.params}, ${formatGB(e.sizeBytes)})`
+            : e.name,
+        value: e.name,
+    }));
+    return [...rows, { title: "custom (hf: URI or .gguf path)…", value: CUSTOM_CHOICE }];
 }
 export async function runDownload(value) {
     gate();
+    let picked = value;
+    if (picked === undefined) {
+        // Prompting needs BOTH ends of the terminal: a TTY stdout to draw on and
+        // a TTY stdin to read from (`agency local download < /dev/null` from a
+        // terminal has a TTY stdout but nothing to read).
+        if (process.stdin.isTTY !== true || process.stdout.isTTY !== true) {
+            // A script that reaches this point asked for a download and did not
+            // get one — print what is available and fail.
+            console.log(formatModelCatalog());
+            console.error("Pass a model: agency local download <name>");
+            process.exit(1);
+        }
+        const answer = await prompts({
+            type: "select",
+            name: "model",
+            message: "Which model do you want to download?",
+            choices: downloadChoices(_listModelNames()),
+        });
+        // Cancellation can surface as a missing key or as null — treat both as
+        // "exit 0, nothing downloaded".
+        if (answer.model == null)
+            return;
+        picked = answer.model;
+        if (picked === CUSTOM_CHOICE) {
+            const custom = await prompts({
+                type: "text",
+                name: "value",
+                message: "hf: URI or .gguf path:",
+            });
+            if (custom.value == null || custom.value === "")
+                return;
+            picked = custom.value;
+        }
+    }
     // Show the source it resolved to (the hf: URI for a name/alias) and the
     // local path it landed at. For a .gguf-path input the two are the same, so
     // the source line is skipped.
-    const source = _resolveModelName(value);
-    const modelPath = await _downloadModel(value);
+    const source = _resolveModelName(picked);
+    const modelPath = await _downloadModel(picked);
     if (source !== modelPath) {
         console.log(`source: ${source}`);
     }

package/dist/lib/cli/localFlag.d.ts

@@ -0,0 +1,12 @@
+import type { ResolvedModelFlag } from "../config.js";
+/** Turn `agency run --local <value>` into the shared model-flag shape:
+ *  resolve the name (curated / alias / hf: URI / .gguf path), download and
+ *  verify if needed (progress prints here, in the parent, before the program
+ *  starts), and pin the llama-cpp provider. Errors (package missing, unknown
+ *  name, failed download) carry user-ready messages from localModels.
+ *
+ *  The path is absolutized before it is baked into config: LlamaCPP rejects a
+ *  bare separator-less filename (ambiguous with a model name), which is what
+ *  a user-supplied `--local model.gguf` would otherwise arrive as, and an
+ *  absolute path also keeps the child process independent of cwd drift. */
+export declare function resolveLocalRunFlag(value: string): Promise<ResolvedModelFlag>;

package/dist/lib/cli/localFlag.js

@@ -0,0 +1,16 @@
+import * as path from "node:path";
+import { _registerLocalModel } from "../stdlib/localModels.js";
+/** Turn `agency run --local <value>` into the shared model-flag shape:
+ *  resolve the name (curated / alias / hf: URI / .gguf path), download and
+ *  verify if needed (progress prints here, in the parent, before the program
+ *  starts), and pin the llama-cpp provider. Errors (package missing, unknown
+ *  name, failed download) carry user-ready messages from localModels.
+ *
+ *  The path is absolutized before it is baked into config: LlamaCPP rejects a
+ *  bare separator-less filename (ambiguous with a model name), which is what
+ *  a user-supplied `--local model.gguf` would otherwise arrive as, and an
+ *  absolute path also keeps the child process independent of cwd drift. */
+export async function resolveLocalRunFlag(value) {
+    const modelPath = await _registerLocalModel(value);
+    return { model: path.resolve(modelPath), explicitProvider: "llama-cpp" };
+}

package/dist/lib/runtime/interrupts.js

@@ -11,6 +11,7 @@ import { isAborted } from "./abortedResult.js";
 import { mergeFor, mergeForIpc } from "./effectMerge.js";
 import { applyOverrides } from "./rewind.js";
 import { loadProviderModules } from "./providerModules.js";
+import { ensureConfiguredLocalProvider } from "./localProvider.js";
 import { installRunPolicyHandler } from "./runPolicyHandler.js";
 import { unwrapServedInvocationOutcome, } from "./invocationUsage.js";
 import { finishServedInvocation } from "./servedInvocationLifecycle.js";
@@ -613,6 +614,7 @@ async function respondToInterruptsCore(args) {
         // is process-global, not part of serialized checkpoint state), so re-register
         // before resuming. Idempotent in-process via loadProviderModules' guard.
         await loadProviderModules(execCtx);
+        await ensureConfiguredLocalProvider(execCtx);
         // This is the first restore on this execCtx — record it as such.
         execCtx._restoreCount++;
         execCtx.statelogClient.checkpointRestored({

package/dist/lib/runtime/localProvider.d.ts

@@ -0,0 +1,76 @@
+import { type LlamaCppModule } from "smoltalk";
+/** 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;
+/** Local require paths first, then the global npm/pnpm roots. Used by the
+ *  install gate (`hasLocalModelSupport`), which only cares whether the
+ *  package is reachable at all. */
+export declare function resolveSmoltalkLlamaCppEntry(): string | null;
+/** The chooseEntryPath decision: what to hand smoltalk, and how the package
+ *  was found (for the `localModelLoaded` statelog event). `entryPath` is
+ *  undefined for a bare import — sources "local" and "none". */
+export type LlamaCppEntryChoice = {
+    entryPath: string | undefined;
+    source: "override" | "local" | "global" | "none";
+};
+/** What to hand smoltalk's loadLlamaCpp: an explicit entry path, or
+ *  undefined for a bare import. Pure — the probes come in as values/thunks so
+ *  tests pin each branch. Precedence:
+ *  1. AGENCY_LLAMA_PROVIDER_MODULE (the test/advanced escape hatch; an ENTRY
+ *     PATH to a plugin-shaped module — a LlamaCPP class + resolveModel),
+ *     absolutized against cwd.
+ *  2. Locally resolvable → undefined: smoltalk imports the bare specifier
+ *     itself (under pnpm its peer instancing picks the right copy).
+ *  3. A global-roots hit → that path (smoltalk cannot see global installs).
+ *  4. Nothing → undefined: smoltalk's import fails with its install hint. */
+export declare function chooseEntryPath(args: {
+    override: string | undefined;
+    cwd: string;
+    localEntry: string | null;
+    globalEntry: () => string | null;
+}): LlamaCppEntryChoice;
+/** The one field of StatelogClient this module needs. Structural so the
+ *  runtime bootstrap can pass its client without this file importing the
+ *  statelog module. */
+type LocalModelEventSink = {
+    localModelLoaded(args: {
+        model?: string;
+        entryPath?: string;
+        entrySource: string;
+    }): Promise<void>;
+};
+/** Bootstrap hook: when the baked/overridden config routes calls to the
+ *  llama-cpp provider, load it eagerly with the probe-assisted entry path.
+ *  smoltalk auto-loads on text() for resolvable installs; this covers the
+ *  global-CLI + global-plugin layout its bare import cannot see. Emits a
+ *  `localModelLoaded` statelog event naming the pinned model and where the
+ *  provider package came from. */
+export declare function ensureConfiguredLocalProvider(execCtx: {
+    smoltalkDefaults?: {
+        provider?: string;
+        model?: string;
+    };
+    statelogClient?: LocalModelEventSink;
+}): Promise<void>;
+/** Like loadLocalProvider, also returning HOW the package was found, for
+ *  callers that emit the `localModelLoaded` event. */
+export declare function loadLocalProviderDetailed(): Promise<{
+    module: LlamaCppModule;
+    choice: LlamaCppEntryChoice;
+}>;
+/** Load smoltalk's optional llama-cpp provider, resolving the package for
+ *  layouts smoltalk cannot see on its own (see chooseEntryPath). Caching,
+ *  idempotency, and registration live in smoltalk's loader, not here. */
+export declare function loadLocalProvider(): Promise<LlamaCppModule>;
+export {};

package/dist/lib/runtime/localProvider.js

@@ -0,0 +1,127 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createRequire } from "node:module";
+import { execFileSync } from "node:child_process";
+import { loadLlamaCpp } from "smoltalk";
+// Cached so we don't shell out repeatedly per process.
+let cachedGlobalRoots = null;
+/** 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 function globalNodeModulesRoots() {
+    if (cachedGlobalRoots !== null) {
+        return cachedGlobalRoots;
+    }
+    const roots = [];
+    for (const cmd of ["npm", "pnpm"]) {
+        try {
+            const out = execFileSync(cmd, ["root", "-g"], {
+                encoding: "utf-8",
+                stdio: ["ignore", "pipe", "ignore"],
+            }).trim();
+            if (out && fs.existsSync(out) && !roots.includes(out)) {
+                roots.push(out);
+            }
+        }
+        catch {
+            /* tool not installed or failed — skip */
+        }
+    }
+    cachedGlobalRoots = roots;
+    return roots;
+}
+/** 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 function resolveSmoltalkLlamaCppFromRoots(roots) {
+    for (const root of roots) {
+        try {
+            const req = createRequire(path.join(root, "..", "_resolver.js"));
+            return req.resolve("smoltalk-llama-cpp");
+        }
+        catch {
+            /* not in this root — try the next */
+        }
+    }
+    return null;
+}
+/** The package entry resolvable from agency's own require paths (in-workspace
+ *  and user-project installs). */
+function localEntry() {
+    try {
+        return createRequire(import.meta.url).resolve("smoltalk-llama-cpp");
+    }
+    catch {
+        return null;
+    }
+}
+/** Local require paths first, then the global npm/pnpm roots. Used by the
+ *  install gate (`hasLocalModelSupport`), which only cares whether the
+ *  package is reachable at all. */
+export function resolveSmoltalkLlamaCppEntry() {
+    return localEntry() ?? resolveSmoltalkLlamaCppFromRoots(globalNodeModulesRoots());
+}
+/** What to hand smoltalk's loadLlamaCpp: an explicit entry path, or
+ *  undefined for a bare import. Pure — the probes come in as values/thunks so
+ *  tests pin each branch. Precedence:
+ *  1. AGENCY_LLAMA_PROVIDER_MODULE (the test/advanced escape hatch; an ENTRY
+ *     PATH to a plugin-shaped module — a LlamaCPP class + resolveModel),
+ *     absolutized against cwd.
+ *  2. Locally resolvable → undefined: smoltalk imports the bare specifier
+ *     itself (under pnpm its peer instancing picks the right copy).
+ *  3. A global-roots hit → that path (smoltalk cannot see global installs).
+ *  4. Nothing → undefined: smoltalk's import fails with its install hint. */
+export function chooseEntryPath(args) {
+    if (args.override !== undefined && args.override !== "") {
+        const abs = path.isAbsolute(args.override)
+            ? args.override
+            : path.resolve(args.cwd, args.override);
+        return { entryPath: abs, source: "override" };
+    }
+    if (args.localEntry !== null)
+        return { entryPath: undefined, source: "local" };
+    const globalPath = args.globalEntry();
+    if (globalPath !== null)
+        return { entryPath: globalPath, source: "global" };
+    return { entryPath: undefined, source: "none" };
+}
+/** Bootstrap hook: when the baked/overridden config routes calls to the
+ *  llama-cpp provider, load it eagerly with the probe-assisted entry path.
+ *  smoltalk auto-loads on text() for resolvable installs; this covers the
+ *  global-CLI + global-plugin layout its bare import cannot see. Emits a
+ *  `localModelLoaded` statelog event naming the pinned model and where the
+ *  provider package came from. */
+export async function ensureConfiguredLocalProvider(execCtx) {
+    if (execCtx.smoltalkDefaults?.provider !== "llama-cpp")
+        return;
+    const { choice } = await loadLocalProviderDetailed();
+    void execCtx.statelogClient?.localModelLoaded({
+        model: execCtx.smoltalkDefaults?.model,
+        entryPath: choice.entryPath,
+        entrySource: choice.source,
+    });
+}
+/** Like loadLocalProvider, also returning HOW the package was found, for
+ *  callers that emit the `localModelLoaded` event. */
+export async function loadLocalProviderDetailed() {
+    const choice = chooseEntryPath({
+        override: process.env.AGENCY_LLAMA_PROVIDER_MODULE,
+        cwd: process.cwd(),
+        localEntry: localEntry(),
+        globalEntry: () => resolveSmoltalkLlamaCppFromRoots(globalNodeModulesRoots()),
+    });
+    const module = await loadLlamaCpp(choice.entryPath === undefined ? undefined : { entryPath: choice.entryPath });
+    return { module, choice };
+}
+/** Load smoltalk's optional llama-cpp provider, resolving the package for
+ *  layouts smoltalk cannot see on its own (see chooseEntryPath). Caching,
+ *  idempotency, and registration live in smoltalk's loader, not here. */
+export async function loadLocalProvider() {
+    return (await loadLocalProviderDetailed()).module;
+}

package/dist/lib/runtime/node.js

@@ -6,6 +6,7 @@ import { AgencyCancelledError, CheckpointError, RestoreSignal, } from "./errors.
 import { ThreadStore } from "./state/threadStore.js";
 import { __initAllRegistered, __initAllRegisteredCallbacks } from "./crossModuleInitRegistry.js";
 import { loadProviderModules } from "./providerModules.js";
+import { ensureConfiguredLocalProvider } from "./localProvider.js";
 import { resolveTraceFilePath } from "./trace/traceWriter.js";
 import { getSubprocessRunInfo } from "./subprocessRunInfo.js";
 import { resolveInvocation } from "./invocationOptions.js";
@@ -146,6 +147,7 @@ async function initFreshExecCtx(execCtx, opts) {
     // Process-global + idempotent (see loadProviderModules), so it is safe and
     // cheap to call on every fresh run.
     await loadProviderModules(execCtx);
+    await ensureConfiguredLocalProvider(execCtx);
     await runInBootstrapFrame(execCtx, () => __initAllRegistered(execCtx));
     if (initializeGlobals) {
         await runInBootstrapFrame(execCtx, () => initializeGlobals(execCtx));

package/dist/lib/statelogClient.d.ts

@@ -266,6 +266,23 @@ export declare class StatelogClient {
         timeTaken?: number;
         cost?: TokenCost;
     }): Promise<void>;
+    /**
+     * Emit a `localModelLoaded` leaf event: which local model the run is
+     * pinned to and where the llama-cpp provider package was resolved from.
+     * `entrySource` is the chooseEntryPath decision — "override"
+     * (AGENCY_LLAMA_PROVIDER_MODULE), "local" (bare import from the local
+     * require paths), or "global" (a global npm/pnpm install root). Emitted
+     * once per process at bootstrap when the baked config names the llama-cpp
+     * provider, and when agency code registers a local model explicitly.
+     */
+    localModelLoaded({ model, entryPath, entrySource, }: {
+        /** The .gguf path (or model name) calls are pinned to, when known. */
+        model?: string;
+        /** Resolved entry file of the provider package, when not a bare import. */
+        entryPath?: string;
+        /** How the provider package was found (see chooseEntryPath). */
+        entrySource: string;
+    }): Promise<void>;
     /**
      * Memory umbrella-span marker events.
      *

package/dist/lib/statelogClient.js

@@ -433,6 +433,23 @@ export class StatelogClient {
             cost,
         });
     }
+    /**
+     * Emit a `localModelLoaded` leaf event: which local model the run is
+     * pinned to and where the llama-cpp provider package was resolved from.
+     * `entrySource` is the chooseEntryPath decision — "override"
+     * (AGENCY_LLAMA_PROVIDER_MODULE), "local" (bare import from the local
+     * require paths), or "global" (a global npm/pnpm install root). Emitted
+     * once per process at bootstrap when the baked config names the llama-cpp
+     * provider, and when agency code registers a local model explicitly.
+     */
+    async localModelLoaded({ model, entryPath, entrySource, }) {
+        await this.post({
+            type: "localModelLoaded",
+            model,
+            entryPath,
+            entrySource,
+        });
+    }
     /**
      * Memory umbrella-span marker events.
      *

package/dist/lib/stdlib/localModelManifest.d.ts

@@ -0,0 +1,14 @@
+/** downloads.json in the models cache dir: resolved model URI → the .gguf
+ *  basename node-llama-cpp stored it under. Written on successful (verified)
+ *  download; read only by the `agency local list` view. Display metadata:
+ *  resolution, downloading, and verification never consult it, so a missing
+ *  or corrupt manifest can mislabel the list and nothing else — and for the
+ *  same reason `recordDownload` NEVER throws (a bookkeeping failure must not
+ *  turn a successful download into a failed command). Writes go through a
+ *  uniquely-named sibling temp file + rename: an interrupted write keeps the
+ *  previous valid manifest, and two concurrent downloaders cannot collide on
+ *  the temp file — they race whole-file on the rename (last writer wins),
+ *  accepted for display metadata. */
+export declare const MANIFEST_FILE = "downloads.json";
+export declare function readDownloadManifest(dir: string): Record<string, string>;
+export declare function recordDownload(dir: string, uri: string, file: string): void;

package/dist/lib/stdlib/localModelManifest.js

@@ -0,0 +1,56 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as crypto from "node:crypto";
+/** downloads.json in the models cache dir: resolved model URI → the .gguf
+ *  basename node-llama-cpp stored it under. Written on successful (verified)
+ *  download; read only by the `agency local list` view. Display metadata:
+ *  resolution, downloading, and verification never consult it, so a missing
+ *  or corrupt manifest can mislabel the list and nothing else — and for the
+ *  same reason `recordDownload` NEVER throws (a bookkeeping failure must not
+ *  turn a successful download into a failed command). Writes go through a
+ *  uniquely-named sibling temp file + rename: an interrupted write keeps the
+ *  previous valid manifest, and two concurrent downloaders cannot collide on
+ *  the temp file — they race whole-file on the rename (last writer wins),
+ *  accepted for display metadata. */
+export const MANIFEST_FILE = "downloads.json";
+export function readDownloadManifest(dir) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(dir, MANIFEST_FILE), "utf-8"));
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return {};
+        }
+        // Null-prototype: on-disk JSON is untrusted, and keys like "__proto__" /
+        // "toString" must behave as plain data (same convention as smoltalk's
+        // provider registry).
+        const out = Object.create(null);
+        for (const [k, v] of Object.entries(parsed)) {
+            if (typeof v === "string")
+                out[k] = v;
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+export function recordDownload(dir, uri, file) {
+    // Unique per writer: a fixed name would make two concurrent downloads race
+    // on the SAME temp file — the loser's rename throws ENOENT after its model
+    // downloaded fine.
+    const tmp = path.join(dir, `${MANIFEST_FILE}.${process.pid}-${crypto.randomBytes(4).toString("hex")}.tmp`);
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        const next = { ...readDownloadManifest(dir), [uri]: file };
+        fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + "\n");
+        fs.renameSync(tmp, path.join(dir, MANIFEST_FILE));
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch {
+            /* never written, or already renamed */
+        }
+        console.warn(`Could not record the download in ${MANIFEST_FILE} (the list view may not mark this model):`, err.message);
+    }
+}

package/dist/lib/stdlib/localModels.d.ts

@@ -35,6 +35,10 @@ export declare const CURATED_LOCAL_MODELS: Record<string, ModelInfo>;
  *      `agency local download` pre-populates what `agency agent --local-model`
  *      reuses). */
 export declare function defaultCacheDir(): string;
+/** The resolved models cache dir (AGENCY_MODELS_DIR env → agency.json
+ *  client.modelsDir → ~/.agency-agent/models). Exported so `agency local
+ *  list` can name where downloads land. */
+export declare function _modelsCacheDir(cacheDir?: string): 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. */
@@ -139,29 +143,6 @@ export declare function _refreshCatalog(opts?: {
     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;
@@ -172,7 +153,11 @@ export declare function _localModelsSupported(): boolean;
  *  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. */
+/** Register the llama-cpp provider into agency's own smoltalk. When called
+ *  from inside a run (the agent's --local path), emit the `localModelLoaded`
+ *  statelog event saying where the provider package came from; the plain CLI
+ *  has no runtime frame, so `__ctx()` is undefined there and nothing is
+ *  emitted. */
 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
@@ -203,6 +188,23 @@ export declare function _registerLocalModel(value: string, cacheDir?: string): P
 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;
+/** The `agency local list` view: every usable model (curated + aliases) with
+ *  a downloaded marker, then cache-dir files no catalog entry claims. A row
+ *  is "downloaded" when the manifest maps its target URI to a file that still
+ *  exists in the cache dir; its SIZE column then shows the on-disk size
+ *  rather than the catalog estimate. Compact and operational — `alias list`
+ *  keeps the verbose per-model catalog with descriptions. Returns the block
+ *  with no trailing newline (the caller's `console.log` adds exactly one). */
+export declare function formatLocalList(args: {
+    dir: string;
+    entries: ModelNameEntry[];
+    manifest: Record<string, string>;
+    files: {
+        name: string;
+        path: string;
+        sizeBytes: 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