akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/integrations/agent/model-map.js

@@ -1,7 +1,6 @@
 // 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/.
-import { randomBytes } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -12,14 +11,9 @@ import { getConfigDir } from "../../core/paths.js";
 import { warnOnce } from "../../core/warn.js";
 import { cloneExecutionJsonObject } from "../../execution/json.js";
 /**
- * Installed and operator-owned model intent aliases (#802 / WP2).
- *
- * The common cascade consumes this loader/expansion API for current runtime
- * execution callers. A recognized alias expands once into exact model and
- * inference defaults at its selecting layer; engine lowerers consume that
- * resolved request and never reinterpret the alias. The independent API also
- * remains usable by WP6/WP7 source and freeze adapters without hard-coding
- * provider mappings.
+ * Installed and operator-owned model intent aliases (#802). `resolveExecution`
+ * expands a recognized alias once, into an exact model and inference defaults
+ * at the layer that chose it; harness builders never reinterpret it.
  */
 export const MODEL_MAP_VERSION = 1;
 let standaloneInstalledModelMapText;
@@ -221,9 +215,8 @@ function mergeProfiles(base, overlay) {
 }
 /**
  * Derive the `{ model, inference }` a model-map profile borrows from a
- * configured engine (#946). Shared verbatim by
- * `execution-definitions.ts`'s own execution-defaults derivation
- * (`engineDefaults`) so the two paths cannot silently diverge. `model` is
+ * configured engine (#946). `resolveExecution` derives an engine's own
+ * defaults with the same function, so the two cannot diverge. `model` is
  * copied verbatim from the engine's own config value; it must already be
  * meaningful for the model-map column's platform (akm does not translate
  * between an engine's connection and an agent platform's own provider
@@ -374,51 +367,29 @@ function modelMapFileError(label, filePath, action) {
     return new ConfigError(`${label} could not be ${action}: ${filePath}.`, "INVALID_CONFIG_FILE", `Ensure ${filePath} is a readable regular file owned by the expected user.`);
 }
 /**
- * Read through a nonblocking, no-follow descriptor and enforce the config-size
- * ceiling before parsing. `optional` recognizes only a true lstat ENOENT as
- * absence; dangling links and every non-regular type are configuration errors.
+ * Read one models.json. `optional` treats absence (including a dangling
+ * symlink) as "no file"; anything that is not a regular file is refused
+ * rather than read, so a FIFO cannot hang the CLI.
  */
 function readModelMapFile(filePath, label, optional) {
-    let targetStat;
+    let stat;
     try {
-        targetStat = fs.statSync(filePath);
+        stat = fs.statSync(filePath);
     }
     catch (error) {
         if (optional && error?.code === "ENOENT")
             return undefined;
         throw modelMapFileError(label, filePath, optional ? "inspected" : "found");
     }
-    if (!targetStat.isFile()) {
+    if (!stat.isFile()) {
         throw new ConfigError(`Unable to read ${label.toLowerCase()} because it is not a readable regular file: ${filePath}.`, "INVALID_CONFIG_FILE", "Replace it with a readable regular models.json file, or a symlink to one.");
     }
-    const nonblock = process.platform !== "win32" && typeof fs.constants.O_NONBLOCK === "number" ? fs.constants.O_NONBLOCK : 0;
-    let fd;
     try {
-        fd = fs.openSync(filePath, fs.constants.O_RDONLY | nonblock);
-        const openedStat = fs.fstatSync(fd);
-        if (!sameFileIdentity(targetStat, openedStat)) {
-            throw new ConfigError(`${label} changed while it was being opened: ${filePath}.`, "INVALID_CONFIG_FILE", "Retry after ensuring no other process is replacing models.json.");
-        }
-        const text = fs.readFileSync(fd, "utf8");
-        fs.closeSync(fd);
-        fd = undefined;
-        return text;
+        return fs.readFileSync(filePath, "utf8");
     }
-    catch (error) {
-        if (error instanceof ConfigError)
-            throw error;
+    catch {
         throw modelMapFileError(label, filePath, "read");
     }
-    finally {
-        if (fd !== undefined) {
-            try {
-                fs.closeSync(fd);
-            }
-            catch {
-                // The actionable read error above remains authoritative.
-            }
-        }
-    }
 }
 /** Resolve the one authoritative external-asset location for this runtime. */
 export function installedModelMapPaths(moduleUrl = import.meta.url) {
@@ -465,139 +436,40 @@ export function loadModelMap(options = {}) {
     return Object.freeze({ map: mergeModelMapLayers(installed, user, options.engines), userPath, userStatus });
 }
 function targetExistsError(target, detail) {
-    return new UsageError(`${detail}: ${target}`, "RESOURCE_ALREADY_EXISTS", "Move the existing target aside, then retry. Use --overwrite only for a stable regular file you intend to replace.");
-}
-function copyIoError(target, action, hint) {
-    return new ConfigError(`Unable to ${action} user models.json at ${target}.`, "INVALID_CONFIG_FILE", hint ?? "Check the configuration directory ownership and permissions, then retry.");
-}
-function inspectCopyTarget(target) {
-    try {
-        return fs.lstatSync(target);
-    }
-    catch (error) {
-        if (error?.code === "ENOENT")
-            return undefined;
-        throw copyIoError(target, "inspect");
-    }
+    return new UsageError(`${detail}: ${target}`, "RESOURCE_ALREADY_EXISTS", "Move the existing target aside, then retry. Use --overwrite only for a regular file you intend to replace.");
 }
-function sameFileIdentity(left, right) {
-    if (!left.isFile() || !right.isFile())
-        return false;
-    if (left.dev !== 0 || left.ino !== 0 || right.dev !== 0 || right.ino !== 0) {
-        return left.dev === right.dev && left.ino === right.ino;
-    }
-    return left.mode === right.mode && left.size === right.size && left.mtimeMs === right.mtimeMs;
-}
-function syncCopyDirectory(directory) {
-    if (process.platform === "win32")
-        return;
-    let fd;
-    try {
-        fd = fs.openSync(directory, fs.constants.O_RDONLY);
-        fs.fsyncSync(fd);
-        fs.closeSync(fd);
-        fd = undefined;
-    }
-    catch (error) {
-        const code = error?.code;
-        if (code !== "EINVAL" && code !== "ENOTSUP")
-            throw error;
-    }
-    finally {
-        if (fd !== undefined) {
-            try {
-                fs.closeSync(fd);
-            }
-            catch {
-                // A preceding sync/open failure is more useful than a cleanup failure.
-            }
-        }
-    }
-}
-function stageDefaultModelMap(target, text) {
-    const stage = `${target}.copy.${process.pid}.${randomBytes(8).toString("hex")}`;
-    try {
-        writeFileAtomic(stage, text, 0o600);
-        return stage;
-    }
-    catch {
-        throw copyIoError(target, "write a staged copy of");
-    }
+function copyIoError(target, action) {
+    return new ConfigError(`Unable to ${action} user models.json at ${target}.`, "INVALID_CONFIG_FILE", "Check the configuration directory ownership and permissions, then retry.");
 }
-/** Explicitly copy validated installed bytes into the normal config directory. */
+/** `akm models copy-defaults`: copy the validated installed map into the config directory. */
 export function copyDefaultModelMap(options = {}) {
     const text = readInstalledModelMapText(options);
     mergeModelMapLayers(parseModelMapLayer(text, "installed models.json"));
     const target = userModelMapPath(options.env);
+    let existing;
     try {
-        fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+        existing = fs.lstatSync(target);
     }
-    catch {
-        throw copyIoError(target, "create the configuration directory for");
+    catch (error) {
+        if (error?.code !== "ENOENT")
+            throw copyIoError(target, "inspect");
     }
-    const existing = inspectCopyTarget(target);
     if (existing && !existing.isFile()) {
         throw targetExistsError(target, "Refusing to replace a non-regular models.json target");
     }
-    if (existing && options.overwrite !== true) {
+    if (existing && options.overwrite !== true)
         throw targetExistsError(target, "User models.json already exists");
-    }
-    const stage = stageDefaultModelMap(target, text);
-    let stagePresent = true;
     try {
-        if (existing === undefined) {
-            try {
-                // Hard-link publication is an atomic no-replace operation: EEXIST
-                // means a racing creator won, and their bytes remain untouched.
-                fs.linkSync(stage, target);
-            }
-            catch (error) {
-                if (error?.code === "EEXIST") {
-                    throw targetExistsError(target, "User models.json was created while defaults were being prepared");
-                }
-                throw copyIoError(target, "publish");
-            }
-            try {
-                fs.unlinkSync(stage);
-                stagePresent = false;
-            }
-            catch {
-                // The target was already published atomically. Cleanup is best-effort
-                // from this point forward; `finally` retries without turning a
-                // successful copy into a false failure.
-            }
-        }
-        else {
-            const current = inspectCopyTarget(target);
-            if (!current || !sameFileIdentity(existing, current)) {
-                throw targetExistsError(target, "User models.json changed while defaults were being prepared");
-            }
-            try {
-                // rename replaces the directory entry itself; it never follows a
-                // symlink inserted after the final identity check.
-                fs.renameSync(stage, target);
-                stagePresent = false;
-            }
-            catch {
-                throw copyIoError(target, "replace");
-            }
-        }
+        fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
     }
-    finally {
-        if (stagePresent) {
-            try {
-                fs.unlinkSync(stage);
-            }
-            catch {
-                // Best-effort cleanup; the target was never published from this path.
-            }
-        }
+    catch {
+        throw copyIoError(target, "create the configuration directory for");
     }
     try {
-        syncCopyDirectory(path.dirname(target));
+        writeFileAtomic(target, text, 0o600);
     }
     catch {
-        throw copyIoError(target, "durably publish", `The target may already exist at ${target}; inspect it before retrying because directory durability could not be confirmed.`);
+        throw copyIoError(target, "write");
     }
     return { path: target, copied: true, overwritten: existing !== undefined };
 }

package/dist/integrations/agent/request-lowering.js

@@ -4,184 +4,109 @@
 import { ConfigError } from "../../core/errors.js";
 import { composeConversationFallbackPrompt } from "./conversation-fallback.js";
 import { composePersonaFallbackPrompt } from "./persona-fallback.js";
-function own(value, key) {
-    return Object.hasOwn(value, key);
-}
-function hasToolSelection(value) {
-    if (value === null)
+/** A tool selection that actually names tools (not omitted, null, or empty). */
+export function hasToolSelection(value) {
+    if (value === null || value === undefined)
         return false;
-    if (typeof value === "string")
-        return value.length > 0;
-    if (Array.isArray(value))
+    if (typeof value === "string" || Array.isArray(value))
         return value.length > 0;
     return Object.keys(value).length > 0;
 }
 function translatesTools(mode, value) {
-    if (!hasToolSelection(value))
-        return true;
     if (mode === "all")
         return true;
-    if (mode === "flat")
-        return typeof value === "string" || Array.isArray(value);
-    if (mode === "sdk") {
-        return (typeof value === "string" ||
-            Array.isArray(value) ||
-            (value !== null && Object.values(value).every((entry) => typeof entry === "boolean")));
-    }
-    return false;
+    if (typeof value === "string" || Array.isArray(value))
+        return mode === "flat" || mode === "sdk";
+    return mode === "sdk" && value !== null && Object.values(value).every((entry) => typeof entry === "boolean");
 }
-function notice(adapter, field) {
-    return Object.freeze({
+/** The notice for a request field a transport does not carry; dispatch continues. */
+export function untranslated(adapter, field) {
+    return {
         code: "untranslated-field",
         severity: "warning",
         adapter,
         field,
         message: `The ${adapter} lowerer does not translate resolved field ${field}; dispatch will continue optimistically.`,
-    });
-}
-function conversationFallbackNotice(adapter) {
-    return Object.freeze({
-        code: "conversation-prompt-composed",
-        severity: "warning",
-        adapter,
-        field: "conversation",
-        message: `The ${adapter} transport has no native multi-message channel; AKM composed the conversation prefix into one deterministic JSON prompt block.`,
-    });
-}
-function selectedExtensionPaths(request) {
-    const out = [];
-    if (own(request, "extensions"))
-        out.push("extensions");
-    if (own(request.command, "extensions"))
-        out.push("command.extensions");
-    const persona = own(request, "persona") ? request.persona : undefined;
-    if (persona && own(persona, "extensions"))
-        out.push("persona.extensions");
-    if (own(request.engine, "extensions"))
-        out.push("engine.extensions");
-    if (own(request.runtime, "extensions"))
-        out.push("runtime.extensions");
-    return out;
+    };
 }
-function sortedUnique(values) {
-    return Object.freeze([...new Set(values)].sort());
+/** Request fields carrying adapter-owned extensions, which no transport translates. */
+export function extensionFields(request) {
+    return [
+        ...(request.extensions ? ["extensions"] : []),
+        ...(request.command.extensions ? ["command.extensions"] : []),
+        ...(request.persona?.extensions ? ["persona.extensions"] : []),
+        ...(request.engine.extensions ? ["engine.extensions"] : []),
+        ...(request.runtime.extensions ? ["runtime.extensions"] : []),
+    ];
 }
 /**
- * Build one harness-owned structural lowerer. Each harness registers the
- * function it gets back beside its argv builder; no global model/provider
- * capability table participates in dispatch.
+ * Build one harness's request builder: map a resolved request onto the
+ * harness-neutral {@link AgentDispatchRequest} its argv builder consumes,
+ * composing into the prompt what the harness has no channel for.
  */
 export function createAgentRequestLowerer(options) {
     const supportedInference = new Set(options.inference ?? []);
     return (_profile, request) => {
-        const translated = new Set(["command.content", "engine"]);
-        for (const field of ["timeoutMs", "workspace", "environment"]) {
-            if (own(request.runtime, field))
-                translated.add(`runtime.${field}`);
-        }
-        const untranslated = new Set();
         const notices = [];
-        const reject = (field) => {
-            untranslated.add(field);
-            notices.push(notice(options.adapter, field));
+        const skip = (field) => {
+            notices.push(untranslated(options.adapter, field));
         };
         let prompt = request.command.content;
-        if (own(request, "conversation")) {
-            translated.add("conversation");
-            if (request.conversation && request.conversation.length > 0) {
-                prompt = composeConversationFallbackPrompt(request.conversation, prompt);
-                notices.push(conversationFallbackNotice(options.adapter));
-            }
+        if (request.conversation && request.conversation.length > 0) {
+            prompt = composeConversationFallbackPrompt(request.conversation, prompt);
+            notices.push({
+                code: "conversation-prompt-composed",
+                severity: "warning",
+                adapter: options.adapter,
+                field: "conversation",
+                message: `The ${options.adapter} transport has no native multi-message channel; AKM composed the conversation prefix into one deterministic JSON prompt block.`,
+            });
         }
-        let systemPrompt;
-        const persona = own(request, "persona") ? request.persona : undefined;
-        const agent = own(request, "agent") ? request.agent : undefined;
-        let nativeAgent;
-        if (persona) {
-            if (options.personaChannel === "native") {
-                systemPrompt = persona.content;
-                translated.add("persona");
-            }
+        const dispatch = { prompt };
+        if (request.persona) {
+            if (options.personaChannel === "native")
+                dispatch.systemPrompt = request.persona.content;
             else {
-                const composed = composePersonaFallbackPrompt(persona.content, prompt, options.adapter);
+                const composed = composePersonaFallbackPrompt(request.persona.content, prompt, options.adapter);
                 prompt = composed.prompt;
                 notices.push(...composed.notices);
-                translated.add("persona");
             }
-            if (typeof agent === "string")
-                translated.add("agent");
         }
-        else if (typeof agent === "string") {
+        else if (typeof request.agent === "string") {
             if (!options.nativeAgentSelector) {
-                throw new ConfigError(`The ${options.adapter} transport cannot consume native agent selector ${JSON.stringify(agent)}.`, "INVALID_CONFIG_FILE");
-            }
-            nativeAgent = agent;
-            translated.add("agent");
-        }
-        else if (own(request, "agent")) {
-            translated.add("agent");
-        }
-        const dispatch = { prompt };
-        if (nativeAgent !== undefined)
-            dispatch.agent = nativeAgent;
-        if (systemPrompt !== undefined)
-            dispatch.systemPrompt = systemPrompt;
-        if (own(request, "model")) {
-            translated.add("model");
-            if (request.model) {
-                dispatch.model = request.model.resolved;
+                throw new ConfigError(`The ${options.adapter} transport cannot consume native agent selector ${JSON.stringify(request.agent)}.`, "INVALID_CONFIG_FILE");
             }
+            dispatch.agent = request.agent;
         }
-        if (own(request, "inference")) {
-            dispatch.inference = request.inference;
-            const inference = request.inference;
-            if (inference && Object.keys(inference).length > 0) {
-                for (const key of Object.keys(inference).sort()) {
-                    const field = `inference.${key}`;
-                    if (supportedInference.has(key))
-                        translated.add(field);
-                    else
-                        reject(field);
-                }
-                if (typeof inference.effort === "string")
-                    dispatch.effort = inference.effort;
-            }
-            else {
-                translated.add("inference");
+        dispatch.prompt = prompt;
+        if (request.model)
+            dispatch.model = request.model.resolved;
+        if (Object.hasOwn(request, "inference")) {
+            dispatch.inference = request.inference ?? null;
+            for (const key of Object.keys(request.inference ?? {}).sort()) {
+                if (!supportedInference.has(key))
+                    skip(`inference.${key}`);
             }
+            if (typeof request.inference?.effort === "string")
+                dispatch.effort = request.inference.effort;
         }
-        if (own(request, "outputSchema")) {
-            if (request.outputSchema === null || options.outputSchema)
-                translated.add("outputSchema");
-            else
-                reject("outputSchema");
-            if (request.outputSchema)
-                dispatch.schema = request.outputSchema;
+        if (request.outputSchema) {
+            if (!options.outputSchema)
+                skip("outputSchema");
+            dispatch.schema = request.outputSchema;
         }
-        if (own(request, "tools")) {
-            const tools = request.tools;
-            if (translatesTools(options.tools, tools))
-                translated.add("tools");
-            else {
+        if (request.tools !== undefined) {
+            // An explicit empty selection still reaches the builder (e.g. an empty allowlist).
+            if (hasToolSelection(request.tools) && !translatesTools(options.tools, request.tools)) {
                 throw new ConfigError(`The ${options.adapter} transport cannot enforce the resolved tool policy.`, "INVALID_CONFIG_FILE");
             }
-            dispatch.tools = tools;
-        }
-        if (own(request.runtime, "settings")) {
-            const settings = request.runtime.settings;
-            if (settings === null || Object.keys(settings).length === 0)
-                translated.add("runtime.settings");
-            else
-                reject("runtime.settings");
+            dispatch.tools = request.tools;
         }
-        for (const field of selectedExtensionPaths(request))
-            reject(field);
-        return Object.freeze({
-            prompt,
-            dispatch: Object.freeze(dispatch),
-            translatedFields: sortedUnique(translated),
-            untranslatedFields: sortedUnique(untranslated),
-            notices: Object.freeze(notices),
-        });
+        const settings = request.runtime.settings;
+        if (settings && Object.keys(settings).length > 0)
+            skip("runtime.settings");
+        for (const field of extensionFields(request))
+            skip(field);
+        return { prompt, dispatch, notices };
     };
 }