akm-cli 0.10.261012-beta → 0.10.261014-beta

package/dist/integrations/agent/resolution.js

@@ -0,0 +1,332 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Where an execution runs: the one place a connection or harness, and the model on
+ * it, are chosen.
+ *
+ *   target  the nearest layer that names a connection or harness, which must be
+ *           configured (a harness by its name, else by its platform): a name that
+ *           is not is an error, never a reason to use the default. None named
+ *           means the default by name, chosen by the work: model work prefers the
+ *           default connection and falls back to the default harness, agent work
+ *           the reverse and falls back to akm's own runtime over the default
+ *           connection.
+ *   model   the nearest layer's `model`: an alias is looked up in the connection's
+ *           (or harness's) `models`, anything else is the exact name; none means
+ *           the first model configured.
+ *   timeout the nearest layer's, else the connection's or harness's, else the one
+ *           default: 600 s for a connection and for model work, none for an agent.
+ *
+ * Layers run farther to nearer, so the last one that says something wins.
+ */
+import path from "node:path";
+import { closestMatch } from "../../core/closest-match.js";
+import { ambiguousDefaultAdvice, defaultConnection, defaultHarness, inheritedConnectionsOf, retiredEngineTargets, unusableEntryAt, } from "../../core/config/config.js";
+import { apiKeyReference } from "../../core/config/credentials.js";
+import { deepMergeConfig } from "../../core/config/deep-merge.js";
+import { STANDARD_ALIASES } from "../../core/config/model-aliases.js";
+import { ConfigError } from "../../core/errors.js";
+import { mergeRequestFields } from "../../core/llm-inference.js";
+import { DURATION_UNITS, parseDuration } from "../../core/time.js";
+import { warnOnce } from "../../core/warn.js";
+import { EXECUTION_MAX_TIMEOUT_MS } from "../../execution/limits.js";
+import { getHarness, HARNESS_NATIVE_AGENT_IDS } from "../harnesses/index.js";
+import { DEFAULT_AGENT_TIMEOUT_MS, DEFAULT_LLM_TIMEOUT_MS } from "./config.js";
+import { getBuiltinAgentProfile } from "./profiles.js";
+/** The keys of a connection that akm reads; every other key is a request field. */
+const CONNECTION_OWNED_KEYS = new Set([
+    "endpoint",
+    "apiKey",
+    "apiKeyFile",
+    "models",
+    "contextLength",
+    "timeoutMs",
+    "concurrency",
+]);
+function present(layer, key) {
+    return layer[key] !== undefined;
+}
+/** The value of the nearest layer that sets `key`; a layer setting `null` ends the search with `null`. */
+function nearest(layers, key) {
+    for (let index = layers.length - 1; index >= 0; index -= 1) {
+        const layer = layers[index];
+        if (layer && present(layer, key))
+            return layer[key];
+    }
+    return undefined;
+}
+/** A timeout as milliseconds (or `null` for none): a whole number, or a duration such as `20m`. */
+export function parseTimeout(value) {
+    if (value === null)
+        return null;
+    const milliseconds = typeof value === "string" ? parseDuration(value, DURATION_UNITS) : value;
+    if (typeof milliseconds !== "number" ||
+        !Number.isInteger(milliseconds) ||
+        milliseconds < 0 ||
+        milliseconds > EXECUTION_MAX_TIMEOUT_MS) {
+        throw new ConfigError("Execution timeout must be null, a whole number of milliseconds, or a duration such as 20m.", "INVALID_CONFIG_FILE");
+    }
+    return milliseconds;
+}
+// ── Inference ───────────────────────────────────────────────────────────────
+/**
+ * Reasoning effort has one word in a request: `reasoningEffort`, which is what
+ * the LLM request body calls it. `effort` is the same setting as an asset's
+ * `effort:` frontmatter spells it, and becomes `reasoningEffort` here, in the one
+ * place every layer's inference is merged, so the nearest layer wins whichever
+ * word it used. When one inference object has both, `reasoningEffort` wins.
+ */
+export function withReasoningEffort(inference) {
+    if (!Object.hasOwn(inference, "effort"))
+        return inference;
+    const { effort, ...rest } = inference;
+    return Object.hasOwn(rest, "reasoningEffort") ? rest : { ...rest, reasoningEffort: effort };
+}
+/** The layers' portable inference merged, nearest wins; a layer that sets `null` clears what is farther. */
+export function mergeLayerInference(layers) {
+    let merged;
+    for (const layer of layers) {
+        if (layer.inference === undefined)
+            continue;
+        merged =
+            layer.inference === null
+                ? null
+                : deepMergeConfig(merged ?? {}, withReasoningEffort(layer.inference));
+    }
+    return merged;
+}
+/**
+ * What the retired `engine` spelling names. While the config file is still in the `engines` form, the connection
+ * or harness that engine became (it may have been renamed); otherwise a connection by that name, else a harness.
+ */
+export function retiredEngineSelection(config, name) {
+    const became = retiredEngineTargets()[name];
+    if (became)
+        return "harness" in became
+            ? { kind: "harness", name: became.harness }
+            : { kind: "connection", name: became.connection };
+    return { kind: config.harnesses?.[name] && !config.connections?.[name] ? "harness" : "connection", name };
+}
+/** The name the nearest layer that names anything gives, and the kind it gave it as. */
+function namedByLayers(config, layers, modelWork) {
+    const order = modelWork ? ["connection", "harness"] : ["harness", "connection"];
+    for (let index = layers.length - 1; index >= 0; index -= 1) {
+        const layer = layers[index];
+        if (!layer)
+            continue;
+        for (const kind of order) {
+            const name = layer[kind];
+            if (typeof name === "string" && name)
+                return { kind, name };
+        }
+        const engine = layer.engine;
+        if (typeof engine === "string" && engine)
+            return retiredEngineSelection(config, engine);
+    }
+    return undefined;
+}
+/**
+ * The connection or harness the default-by-name rule picks for this work, if either is configured. Model work
+ * skips a harness that is set not to do it (`modelWork: false`); a call that names the harness still runs on it.
+ */
+function defaultTarget(config, modelWork) {
+    const connection = defaultConnection(config);
+    const found = defaultHarness(config);
+    const harness = found && !(modelWork && found.harness.modelWork === false) ? found : undefined;
+    const asConnection = connection && { kind: "connection", ...connection };
+    const asHarness = harness && { kind: "harness", ...harness };
+    return modelWork ? (asConnection ?? asHarness) : (asHarness ?? asConnection);
+}
+/** The names of the configured harnesses that run `platform`: an entry's `platform`, else its key. */
+function harnessesOnPlatform(config, platform) {
+    return Object.entries(config.harnesses ?? {})
+        .filter(([name, harness]) => (harness.platform ?? name) === platform)
+        .map(([name]) => name);
+}
+/**
+ * The harness a `harness:` selector names: the one called that, else the one that runs that platform (a shared
+ * asset says `claude` whatever setup called the entry). Several on a platform: the one named `default`, else none,
+ * never the first.
+ */
+function harnessNamed(config, selector) {
+    const harnesses = config.harnesses ?? {};
+    const onPlatform = harnessesOnPlatform(config, selector);
+    const name = Object.hasOwn(harnesses, selector)
+        ? selector
+        : onPlatform.length === 1
+            ? onPlatform[0]
+            : onPlatform.find((candidate) => candidate === "default");
+    const harness = name === undefined ? undefined : harnesses[name];
+    return name !== undefined && harness ? { name, harness } : undefined;
+}
+/** The error for a connection or harness that was named and is not configured: what was named, what is configured, and the nearest name. */
+export function selectionNotConfigured(config, kind, name) {
+    const label = kind === "connection" ? "Connection" : "Harness";
+    const plural = kind === "connection" ? "connections" : "harnesses";
+    const configured = Object.keys((kind === "connection" ? config.connections : config.harnesses) ?? {});
+    const near = closestMatch(name, configured, Math.max(1, Math.floor(name.length / 3)));
+    const unusable = unusableEntryAt(`${kind === "connection" ? "connections" : "harnesses"}.${name}`);
+    const sharing = kind === "harness" ? harnessesOnPlatform(config, name) : [];
+    return new ConfigError([
+        `${label} "${name}" is not configured.`,
+        unusable
+            ? `config.json has a ${kind} by that name that akm ignores, because ${unusable.why}.`
+            : sharing.length > 1
+                ? `${sharing.map((candidate) => `"${candidate}"`).join(", ")} all run the ${name} platform and none is named "default": name one of them.`
+                : configured.length > 0
+                    ? `Configured ${plural}: ${configured.join(", ")}.`
+                    : `No ${plural} are configured.`,
+        near ? `Did you mean "${near}"?` : undefined,
+    ]
+        .filter((sentence) => sentence !== undefined)
+        .join(" "), "SELECTION_NOT_CONFIGURED");
+}
+function selectTarget(input) {
+    const modelWork = input.modelWork === true;
+    const named = namedByLayers(input.config, input.layers, modelWork);
+    if (named) {
+        const connection = named.kind === "connection" ? input.config.connections?.[named.name] : undefined;
+        const harness = named.kind === "harness" ? harnessNamed(input.config, named.name) : undefined;
+        if (connection)
+            return { kind: "connection", name: named.name, connection };
+        if (harness)
+            return { kind: "harness", ...harness };
+        // A target that was asked for by name is never replaced by the default: that could send a private call to a remote
+        // service, or a call that must not touch files to an agent that can. Defaults apply only when nothing was named.
+        throw selectionNotConfigured(input.config, named.kind, named.name);
+    }
+    const target = defaultTarget(input.config, modelWork);
+    if (target)
+        return target;
+    const ambiguous = ambiguousDefaultAdvice(input.config);
+    const declined = modelWork ? defaultHarness(input.config) : undefined;
+    throw new ConfigError((ambiguous ? `${ambiguous}.` : undefined) ??
+        (declined?.harness.modelWork === false
+            ? `No connection is configured, and harness "${declined.name}" is set not to run akm's model calls (modelWork: false), so there is nothing to run model work on. Add a connection with \`akm setup --endpoint URL\`.`
+            : modelWork
+                ? "No connection or harness is configured, so there is nothing to run model work on."
+                : "No harness or connection is configured, so there is nothing to run agent work on."), modelWork ? "LLM_NOT_CONFIGURED" : "AGENT_NOT_CONFIGURED");
+}
+// ── Model ───────────────────────────────────────────────────────────────────
+/** Every alias this config knows: the standard ones and any a connection or harness maps. */
+function knownAliases(config) {
+    const aliases = new Set(STANDARD_ALIASES);
+    for (const entry of [...Object.values(config.connections ?? {}), ...Object.values(config.harnesses ?? {})]) {
+        for (const alias of Object.keys(entry.models ?? {}))
+            aliases.add(alias);
+    }
+    return aliases;
+}
+/**
+ * The entry a requested model names in `models`: the alias's entry; the exact name
+ * when it is not an alias; the first entry otherwise (no request, or an alias this
+ * map does not carry).
+ */
+function modelEntry(models, requested, aliases) {
+    if (requested !== undefined && Object.hasOwn(models, requested))
+        return models[requested];
+    if (requested !== undefined && !aliases.has(requested))
+        return requested;
+    return Object.values(models)[0];
+}
+// ── Runners ─────────────────────────────────────────────────────────────────
+/** The first timeout that is set; `null` is a timeout (none), so it ends the search. */
+function firstTimeout(...timeouts) {
+    return timeouts.find((timeout) => timeout !== undefined) ?? null;
+}
+/** What bounds a run when nothing sets a timeout, on a connection or a harness alike: agent work runs until it finishes, a model call stops at the model-call default. */
+function defaultTimeout(modelWork) {
+    return modelWork ? DEFAULT_LLM_TIMEOUT_MS : DEFAULT_AGENT_TIMEOUT_MS;
+}
+/** The timeout the nearest layer sets, if any. */
+function layerTimeout(layers) {
+    const value = nearest(layers, "timeout");
+    return value === undefined ? undefined : parseTimeout(value);
+}
+function connectionRunner(name, connection, requested, aliases, layers, modelWork, inherited) {
+    const entry = modelEntry(connection.models ?? {}, requested, aliases);
+    if (entry === undefined) {
+        throw new ConfigError(`Connection "${name}" lists no models, so no model can be chosen. Name one with \`akm models set fast <model> --connection ${name}\`, or run \`akm setup\`.`, "INVALID_CONFIG_FILE");
+    }
+    const { model, ...entryFields } = typeof entry === "string" ? { model: entry } : entry;
+    const connectionFields = Object.fromEntries(Object.entries(connection).filter(([key]) => !CONNECTION_OWNED_KEYS.has(key)));
+    const inference = mergeLayerInference(layers);
+    return {
+        kind: "connection",
+        name,
+        endpoint: connection.endpoint,
+        model,
+        request: mergeRequestFields(connectionFields, entryFields),
+        ...(inference && Object.keys(inference).length > 0 ? { inference } : {}),
+        ...(apiKeyReference(connection.apiKey) !== undefined ? { apiKey: connection.apiKey } : {}),
+        ...(inherited ? { storedKey: false } : {}),
+        ...(connection.contextLength !== undefined ? { contextLength: connection.contextLength } : {}),
+        ...(connection.concurrency !== undefined ? { concurrency: connection.concurrency } : {}),
+        timeoutMs: firstTimeout(layerTimeout(layers), connection.timeoutMs, defaultTimeout(modelWork)),
+    };
+}
+/** The model name a harness alias holds. A harness is passed the name only, so an entry's request fields (a connection's) are ignored, with a word. */
+function harnessAliasModel(name, alias, entry) {
+    if (typeof entry === "string")
+        return entry;
+    if (Object.keys(entry).length > 1) {
+        warnOnce(`resolution:alias-fields:${name}:${alias}`, `Harness "${name}" is passed only the model name of "${alias}"; the other fields of that entry are ignored.`);
+    }
+    return entry.model;
+}
+/**
+ * The harness model a request names, or `undefined` when the harness is left to pick
+ * its own: a layer that sets `model: null` asks for exactly that.
+ */
+function harnessModel(name, platform, harness, requested, aliases) {
+    if (requested === null)
+        return undefined;
+    const own = harness.models ?? {};
+    const shipped = getHarness(platform)?.models ?? {};
+    const [first] = Object.entries(own);
+    if (requested === undefined)
+        return first ? harnessAliasModel(name, first[0], first[1]) : undefined;
+    const entry = Object.hasOwn(own, requested) ? own[requested] : undefined;
+    if (entry !== undefined)
+        return harnessAliasModel(name, requested, entry);
+    if (Object.hasOwn(shipped, requested))
+        return shipped[requested];
+    if (!aliases.has(requested))
+        return requested;
+    // A harness with no map at all picks its own model whatever is asked; only one that maps others is worth a word.
+    if (Object.keys(own).length > 0 || Object.keys(shipped).length > 0) {
+        warnOnce(`resolution:no-model:${name}:${requested}`, `Harness "${name}" has no model for "${requested}", so it uses its own default. Map one under harnesses.${name}.models.`);
+    }
+    return undefined;
+}
+function harnessRunner(name, harness, requested, aliases, layers, modelWork) {
+    const platform = harness.platform ?? name;
+    const builtin = getBuiltinAgentProfile(platform);
+    if (harness.agent !== undefined && !HARNESS_NATIVE_AGENT_IDS.has(platform)) {
+        warnOnce(`resolution:agent:${name}`, `Harness "${name}" (${platform}) has no native agents; its agent setting is ignored.`);
+    }
+    const model = harnessModel(name, platform, harness, requested, aliases);
+    return {
+        kind: "harness",
+        name,
+        platform,
+        bin: harness.bin ?? builtin?.bin ?? platform,
+        args: harness.args ?? builtin?.args ?? [],
+        ...(harness.workspace !== undefined ? { workspace: path.resolve(harness.workspace) } : {}),
+        ...(harness.agent !== undefined && HARNESS_NATIVE_AGENT_IDS.has(platform) ? { agent: harness.agent } : {}),
+        ...(model !== undefined ? { model } : {}),
+        timeoutMs: firstTimeout(layerTimeout(layers), harness.timeoutMs, defaultTimeout(modelWork)),
+    };
+}
+/** Where this execution runs and with which model, from the config and the layers that speak for it. */
+export function resolveTarget(input) {
+    const target = selectTarget(input);
+    const requestedModel = nearest(input.layers, "model");
+    const requested = typeof requestedModel === "string" && requestedModel ? requestedModel : undefined;
+    const aliases = knownAliases(input.config);
+    const modelWork = input.modelWork === true;
+    return target.kind === "connection"
+        ? connectionRunner(target.name, target.connection, requested, aliases, input.layers, modelWork, inheritedConnectionsOf(input.config).has(target.name))
+        : harnessRunner(target.name, target.harness, requestedModel === null ? null : requested, aliases, input.layers, modelWork);
+}