akm-cli 0.10.261015-beta → 0.10.261016-beta

package/dist/core/config/schema/connections.js

@@ -12,7 +12,7 @@
  */
 import { z } from "zod";
 import { WORKFLOW_MAX_TIMEOUT_MS } from "../../../workflows/resource-limits.js";
-import { connectionEndpoint, engineName, envReferenceApiKey, nonEmptyString, positiveInt, retiredApiKeyFile, } from "./primitives.js";
+import { connectionEndpoint, engineName, envReferenceApiKey, nonEmptyString, OpaqueFieldSchema, positiveInt, retiredApiKeyFile, } from "./primitives.js";
 /**
  * Timeouts share the workflow ceiling: a larger value would pass config
  * validation and then fail every run with an unlocated "invocation is invalid".
@@ -24,7 +24,10 @@ export const timeoutMsField = z.union([positiveInt.max(WORKFLOW_MAX_TIMEOUT_MS),
  * request fields of its own. The object is listed first so a JSON value given to
  * `akm config set` is read as one.
  */
-export const ModelEntrySchema = z.union([z.object({ model: nonEmptyString }).catchall(z.unknown()), nonEmptyString]);
+export const ModelEntrySchema = z.union([
+    z.object({ model: nonEmptyString }).catchall(OpaqueFieldSchema),
+    nonEmptyString,
+]);
 /** Alias (`fast`, `balanced`, `reasoning`, or any the user adds) to the model it names. */
 export const ModelAliasesSchema = z.record(nonEmptyString, ModelEntrySchema);
 export const ConnectionSchema = z
@@ -37,5 +40,5 @@ export const ConnectionSchema = z
     timeoutMs: timeoutMsField,
     concurrency: positiveInt.optional(),
 })
-    .catchall(z.unknown());
+    .catchall(OpaqueFieldSchema);
 export const ConnectionsSchema = z.record(engineName, ConnectionSchema);

package/dist/core/config/schema/harnesses.js

@@ -13,7 +13,14 @@ import { ModelAliasesSchema, timeoutMsField } from "./connections.js";
 import { engineName, nonEmptyString } from "./primitives.js";
 export const HarnessSchema = z
     .object({
-    platform: z.enum(HARNESS_CONFIG_PLATFORMS).optional(),
+    // Zod 4's message for a value outside an enum no longer quotes the value; the warning for a dropped harness should.
+    platform: z
+        .enum(HARNESS_CONFIG_PLATFORMS, {
+        error: (issue) => issue.code === "invalid_value"
+            ? `${JSON.stringify(issue.input)} is not one of ${HARNESS_CONFIG_PLATFORMS.join(", ")}`
+            : undefined,
+    })
+        .optional(),
     bin: nonEmptyString.optional(),
     args: z.array(z.string()).optional(),
     workspace: nonEmptyString.optional(),

package/dist/core/config/schema/primitives.js

@@ -12,11 +12,22 @@ import { redactUrlCredentials } from "../../redaction.js";
 import { isSecretRefToken } from "../../ref-token.js";
 import { warnOnce } from "../../warn.js";
 import { ENGINE_NAME_PATTERN_SOURCE } from "../engine-semantics.js";
+// Zod 4 reports a map key its key schema rejects as "Invalid key in record" and keeps that schema's own message
+// (the naming rule, the slug rule) inside the issue; config errors and warnings print only the outer message.
+z.config({
+    customError: (issue) => issue.code === "invalid_key" ? issue.issues.map((inner) => inner.message).join("; ") : undefined,
+});
 /** Persisted config schema version. Package prerelease/patch versions do not change this value. */
 export const CURRENT_CONFIG_VERSION = "0.9.0";
 // ── Reusable atomic schemas ─────────────────────────────────────────────────
 /** Positive integer (used for tokens, timeouts, batch sizes). */
 export const positiveInt = z.number().int().positive();
+/**
+ * The catchall of an object whose extra keys are the endpoint's to define (a connection's request fields):
+ * any key, contents left alone. The config walker knows it by identity: a `.passthrough()` object also has an
+ * `unknown` catchall, and its extra keys are ones akm does not define.
+ */
+export const OpaqueFieldSchema = z.unknown();
 /** Non-negative finite number (used for scores, weights, days). */
 export const nonNegativeNumber = z.number().finite().min(0);
 /** Non-empty string (rejects "" and whitespace-only). */
@@ -92,7 +103,7 @@ export const connectionEndpoint = z.string().superRefine((value, ctx) => {
         warnOnce(`connectionEndpoint:userinfo:${shown}`, `Config endpoint "${shown}" embeds a username/password; move the credential out of the URL (apiKey: "$VAR", or credentials.json).`);
     }
 });
-export const ExtraParamsSchema = z.record(z.unknown()).superRefine((value, ctx) => {
+export const ExtraParamsSchema = z.record(z.string(), z.unknown()).superRefine((value, ctx) => {
     for (const issue of validateExtraParams(value)) {
         ctx.addIssue({ code: z.ZodIssueCode.custom, path: issue.path, message: issue.message });
     }

package/dist/core/config/schema/sources-bundles.js

@@ -16,7 +16,7 @@ import { isBundleSlug } from "../../asset/asset-ref.js";
 import { httpUrl, isApiKeyReference, nonEmptyString, positiveInt } from "./primitives.js";
 const VALID_ADAPTER_IDS_SET = new Set(VALID_ADAPTER_IDS);
 // ── Sources / registries / installed ────────────────────────────────────────
-const SourceConfigEntryOptionsSchema = z.record(z.unknown());
+const SourceConfigEntryOptionsSchema = z.record(z.string(), z.unknown());
 export const SourceConfigEntrySchema = z
     .object({
     type: nonEmptyString,
@@ -74,7 +74,7 @@ export const RegistryConfigEntrySchema = z
     name: z.string().min(1).optional(),
     enabled: z.boolean().optional(),
     provider: z.string().min(1).optional(),
-    options: z.record(z.unknown()).optional(),
+    options: z.record(z.string(), z.unknown()).optional(),
 })
     .passthrough();
 // ── Bundles ─────────────────────────────────────────────────────────────────

package/dist/core/npm-package.js

@@ -12,8 +12,10 @@
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { writeResponseToFileCapped } from "../runtime.js";
+import { sleep, writeResponseToFileCapped } from "../runtime.js";
 import { fetchWithRetry, isRecord } from "./common.js";
+import { releaseLock } from "./file-lock.js";
+import { formatLockHolderPid, tryAcquireRunLock } from "./run-lock.js";
 import { extractTarGzMembers } from "./tar.js";
 export const NPM_REGISTRY = "https://registry.npmjs.org";
 /** The `sha512-<base64>` integrity npm records for a tarball. */
@@ -47,14 +49,50 @@ async function registryDocument(url) {
     }
     return { tarball: dist.tarball, integrity: dist.integrity };
 }
+/** How long a fetch waits for another process's fetch into the same directory: a large tarball on a slow link takes minutes. */
+const FETCH_LOCK_TIMEOUT_MS = 600_000;
 /**
- * Keep members of `name@version`'s tarball in `directory`, each as `file`: the registry document of that one version,
- * its tarball, the check against the sha512 integrity the registry lists before anything is extracted, then each
- * member by temp file and rename (mode 0755), in the order given. Two akm processes fetching at once both finish: a
- * rename that loses to the other leaves the file the other made.
+ * Keep members of `name@version`'s tarball in `directory`, each as `file`. One fetch runs per directory at a time: the
+ * processes fetching there, this one included, wait on a lock file in it, and a dead holder's lock is reclaimed.
  */
 export async function fetchNpmPackageFiles(name, version, directory, files) {
     fs.mkdirSync(directory, { recursive: true });
+    const lock = path.join(directory, "fetch.lock");
+    const deadline = Date.now() + FETCH_LOCK_TIMEOUT_MS;
+    for (;;) {
+        const attempt = tryAcquireRunLock(lock, { label: "fetch" });
+        if (attempt.state === "acquired") {
+            try {
+                return await fetchHoldingLock(name, version, directory, files);
+            }
+            finally {
+                releaseLock(attempt.ownership);
+            }
+        }
+        if (Date.now() >= deadline) {
+            throw new Error(`another akm process (pid ${formatLockHolderPid(attempt.holder)}) is still fetching into ${directory} (lock ${lock})`);
+        }
+        await sleep(100);
+    }
+}
+/** Whether `file` is in place whole: files only ever arrive by rename, so an executable regular file is complete. */
+function isExecutableFile(file) {
+    try {
+        fs.accessSync(file, fs.constants.X_OK);
+        return fs.statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The registry document of that one version, its tarball, the check against the sha512 integrity the registry lists
+ * before anything is extracted, then each member by temp file and rename (mode 0755), in the order given. A fetch that
+ * finds every file in place downloads nothing, and a file in place at the size the tarball holds is never renamed over.
+ */
+async function fetchHoldingLock(name, version, directory, files) {
+    if (files.every(({ file }) => isExecutableFile(path.join(directory, file))))
+        return;
     const download = path.join(directory, `.download-${process.pid}.tgz`);
     const partial = (file) => path.join(directory, `.${file}-${process.pid}.tmp`);
     try {
@@ -70,15 +108,12 @@ export async function fetchNpmPackageFiles(name, version, directory, files) {
         const sizes = await extractTarGzMembers(download, new Map(files.map(({ member, file }) => [member, partial(file)])));
         for (const { member, file } of files) {
             const target = path.join(directory, file);
+            // A whole file in place (an akm without this lock may have made it) stands: a rename would unlink a binary that
+            // may be running on Linux and fails on Windows.
+            if (isExecutableFile(target) && fs.statSync(target).size === sizes.get(member))
+                continue;
             fs.chmodSync(partial(file), 0o755);
-            try {
-                fs.renameSync(partial(file), target);
-            }
-            catch (error) {
-                // Where a file in use cannot be replaced, the other process's file stands.
-                if (!fs.existsSync(target) || fs.statSync(target).size !== sizes.get(member))
-                    throw error;
-            }
+            fs.renameSync(partial(file), target);
         }
     }
     finally {

package/dist/output/renderers.js

@@ -217,8 +217,8 @@ const agentMdRenderer = {
     },
 };
 // ── 4. knowledge-md ──────────────────────────────────────────────────────────
-const KNOWLEDGE_ACTION = "Reference material - read the content below. For a large document, read one section with `akm show <ref>#fragment` " +
-    "(an unmatched #fragment lists the available slugs).";
+const KNOWLEDGE_ACTION = "Reference material - read the content below. For a large document, run `akm show <ref> --detail brief` for its " +
+    "outline (`toc`, no body), then `akm show <ref>#<slug>` for only the sections you need.";
 const knowledgeMdRenderer = {
     name: "knowledge-md",
     buildShowResponse(ctx) {

package/dist/output/shapes/helpers.js

@@ -348,6 +348,7 @@ export function shapeShowOutput(result, detail, shape = "human") {
             "editHint",
             "description",
             "action",
+            "toc",
             "content",
             "template",
             "prompt",
@@ -381,6 +382,7 @@ export function shapeShowOutput(result, detail, shape = "human") {
         "action",
         "description",
         "tags",
+        "toc",
         "content",
         "template",
         "prompt",

package/dist/output/text/show-format.js

@@ -59,6 +59,13 @@ export function formatShowPlain(r, detail) {
         if (r.schemaVersion !== undefined)
             lines.push(`schemaVersion: ${String(r.schemaVersion)}`);
     }
+    if (Array.isArray(r.toc) && r.toc.length > 0) {
+        lines.push("");
+        lines.push("toc:");
+        for (const heading of r.toc) {
+            lines.push(`  ${"#".repeat(heading.level)} ${heading.text} (#${heading.slug}, line ${heading.startLine})`);
+        }
+    }
     const links = typeof r.links === "object" && r.links !== null ? r.links : undefined;
     if (links) {
         lines.push("");

package/dist/registry/semver.js

@@ -41,6 +41,18 @@ export function isSemverRange(input) {
 export function maxSatisfying(versions, range) {
     return semver.maxSatisfying(versions, range) ?? undefined;
 }
+/**
+ * Highest of `versions` in semver order, prereleases included (`0.10.1-beta` sorts above `0.9.30`). Invalid entries
+ * are ignored; `undefined` when none is valid. Use this to order known versions, not `maxSatisfying(versions, "*")`,
+ * which skips every prerelease.
+ */
+export function highestVersion(versions) {
+    return semver.rsort(versions.filter((version) => semver.valid(version) !== null))[0];
+}
+/** True when `version` is a valid semver prerelease (`1.2.3-beta`). */
+export function isPrerelease(version) {
+    return semver.valid(version) !== null && semver.prerelease(version) !== null;
+}
 /** True when `version` satisfies `range` (both real semver forms). False for an invalid version or range. */
 export function satisfiesRange(version, range) {
     return semver.satisfies(version, range);