akm-cli 0.10.261012-beta → 0.10.261014-beta

package/dist/core/endpoint-url.js

@@ -0,0 +1,47 @@
+// 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/.
+/**
+ * How akm reads a connection's `endpoint`: the OpenAI-compatible base URL
+ * (`…/v1`) or the chat-completions URL itself. The endpoint is a URL, so only
+ * its pathname is edited here; a query string (an `api-version`, say) stays
+ * where it is, after the pathname, and a fragment, which is never sent, goes.
+ * Every consumer of an endpoint (the chat client, model listing, health probes,
+ * setup, the stored-key binding, akm's own runtime) reads it through this
+ * one module.
+ */
+/** The operation a complete endpoint URL may end with. */
+const OPERATION_SUFFIX = /\/(?:chat\/completions|embeddings)$/;
+function parse(endpoint) {
+    try {
+        return new URL(endpoint);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The pathname of the endpoint's base: no trailing slash, no `/chat/completions` or `/embeddings`. */
+function basePathname(url) {
+    return url.pathname.replace(/\/+$/, "").replace(OPERATION_SUFFIX, "");
+}
+function withPathname(url, pathname) {
+    url.hash = "";
+    url.pathname = pathname;
+    const text = url.toString();
+    // A bare host serializes with a "/" the endpoint never had.
+    return pathname === "" && url.search === "" ? text.replace(/\/$/, "") : text;
+}
+/** The base of an OpenAI-compatible endpoint: the URL without `/chat/completions`, `/embeddings` or a trailing slash. */
+export function openAiBaseUrl(endpoint) {
+    const url = parse(endpoint);
+    return url ? withPathname(url, basePathname(url)) : endpoint;
+}
+/** The URL of one operation (`chat/completions`, `models`) of the endpoint. */
+export function openAiOperationUrl(endpoint, operation) {
+    const url = parse(endpoint);
+    return url ? withPathname(url, `${basePathname(url)}/${operation}`) : `${endpoint}/${operation}`;
+}
+/** Whether two endpoints are the same server: the same base, however either is spelled. */
+export function sameEndpoint(a, b) {
+    return openAiBaseUrl(a) === openAiBaseUrl(b);
+}

package/dist/core/env-secret-ref.js

@@ -13,11 +13,14 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import { resolveConceptOwner } from "../indexer/lookup/adapter-concept-owner.js";
 import { resolveSourceEntries } from "../indexer/search/search-source.js";
+import { isFileOrFileSymlink } from "../indexer/walk/walker.js";
 import { resolveSourcesForOrigin } from "../registry/origin-resolve.js";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "./asset/asset-create.js";
 import { assetPathForName, deriveCanonicalAssetName } from "./asset/asset-placement.js";
-import { displayRef, isFullRefInput, parseRefInput } from "./asset/resolve-ref.js";
+import { makeBundleRef, parseBundleRef } from "./asset/asset-ref.js";
+import { conceptIdFromTypeName, displayRef, parseRefInput, typeNameFromConceptId } from "./asset/resolve-ref.js";
 import { isWithin } from "./common.js";
 import { loadConfig } from "./config/config.js";
 import { NotFoundError, UsageError } from "./errors.js";
@@ -51,7 +54,7 @@ export function listEnvsRecursive(listKeysFn, config = loadConfig()) {
                     walk(full);
                     continue;
                 }
-                if (!entry.isFile())
+                if (!entry.isFile() && !(entry.isSymbolicLink() && isFileOrFileSymlink(full)))
                     continue;
                 if (entry.name !== ".env" && !entry.name.endsWith(".env"))
                     continue;
@@ -71,33 +74,64 @@ export function listEnvsRecursive(listKeysFn, config = loadConfig()) {
     return result;
 }
 export function parseEnvRef(ref) {
-    // Accept a bare env name (`prod`, `sub/prod`) or the new-grammar
-    // `[bundle//]env/name` conceptId. A bare name's leading segment maps to no
-    // asset type, so it is qualified with the `env/` conceptId prefix; anything
-    // already a full new-grammar ref is parsed as-is.
-    return parseRefInput(isFullRefInput(ref) ? ref : `env/${ref}`);
+    return parseTypedRef(ref, "env", "env/<name>");
 }
-export function findEnvSource(origin, type, name) {
-    const sources = resolveSourceEntries(undefined, loadConfig());
-    if (sources.length === 0) {
-        throw new UsageError("No bundles configured. Run `akm bundle create` to create your working bundle.");
+/**
+ * Parse `ref` as a `[bundle//]conceptId` of the given asset type. There is no
+ * bare-name form: `prod` is a usage error that also names the ref it probably
+ * meant (`env/prod`), as text only — the suggestion is never resolved or accepted.
+ */
+function parseTypedRef(ref, type, form) {
+    let parsed;
+    try {
+        parsed = parseRefInput(ref);
     }
-    const candidates = origin ? resolveSourcesForOrigin(origin, sources) : sources;
-    const typeDir = type === "env" ? "env" : "secrets";
-    const member = candidates.find((source) => fs.existsSync(assetPathForName(type, path.join(source.path, typeDir), name)));
-    if (member)
-        return member;
-    if (!origin) {
-        const fallback = candidates[0];
-        if (fallback)
-            return fallback;
-        throw new UsageError("No bundles configured. Run `akm bundle create` to create your working bundle.");
+    catch (error) {
+        if (!(error instanceof NotFoundError))
+            throw error;
     }
-    const named = candidates[0];
-    if (!named) {
-        throw new NotFoundError(`Source not found for origin: ${origin}`);
+    if (parsed?.type !== type) {
+        const bare = parseBundleRef(ref);
+        const hint = typeNameFromConceptId(bare.conceptId) === undefined
+            ? ` Did you mean "${makeBundleRef(bare.bundle, conceptIdFromTypeName(type, bare.conceptId))}"?`
+            : "";
+        throw new UsageError(`Expected ${type === "env" ? "an" : "a"} ${type} ref (${form} or <bundle>//${form}); got "${ref}". Write the full ref.${hint}`, "INVALID_FLAG_VALUE");
+    }
+    return parsed;
+}
+/** The bundle and file that own an env or secret ref right now, or undefined. Sensitive files resolve too. */
+function findEnvSecretOwner(origin, conceptId) {
+    return resolveConceptOwner({ bundle: origin, conceptId }, resolveSourceEntries(undefined, loadConfig()), {
+        includeSensitive: true,
+    });
+}
+/**
+ * The file that owns any asset ref right now (the asset type its conceptId
+ * names, and the bundle-qualified spelling of the ref), or undefined when no
+ * bundle owns it. The lookup behind `${ref}` tokens.
+ */
+export function resolveRefOwner(ref) {
+    const { bundle, conceptId } = parseBundleRef(ref);
+    const match = findEnvSecretOwner(bundle, conceptId);
+    return (match && {
+        absPath: match.owner.path,
+        type: typeNameFromConceptId(conceptId)?.type,
+        ref: makeBundleRef(match.bundleId, conceptId),
+    });
+}
+/**
+ * Is `bundle` the id of an installed bundle in the active source set? The predicate `${ref}` substitution uses to
+ * tell a qualified ref from shell text. A source set that cannot be read (for example `AKM_BUNDLE_DIR` naming a
+ * disabled bundle) answers "not installed", so shell text never raises a config error; a real ref then fails where
+ * it is resolved, with that error.
+ */
+export function isInstalledBundle(bundle) {
+    try {
+        return resolveSourcesForOrigin(bundle, resolveSourceEntries(undefined, loadConfig())).length > 0;
+    }
+    catch {
+        return false;
     }
-    return named;
 }
 /**
  * `config` defaults to the real `loadConfig()`, same as {@link displayDefaultBundle}.
@@ -112,31 +146,28 @@ export function makeEnvRef(name, source, config = loadConfig()) {
     return displayRef({ type: "env", name, bundleId: source?.registryId }, displayDefaultBundle(source, config));
 }
 /**
- * Resolve an env ref to an absolute `.env` path. Accepts the `env/<name>`
- * conceptId (or a bare name, auto-qualified into it). The path is returned
- * even when the file does not yet exist (so `create` writes under `env/`).
+ * Resolve an env ref to the absolute `.env` path that owns it right now.
+ * Accepts a full `[bundle//]env/<name>` ref.
+ * Throws `NotFoundError` when no bundle owns it; creating one goes through
+ * {@link resolveEnvWriteTarget}.
  */
 export function resolveEnvPath(ref) {
     const parsed = parseEnvRef(ref);
-    if (parsed.type !== "env") {
-        throw new UsageError(`Expected an env ref (env/<name>); got "${ref}".`);
-    }
-    const source = findEnvSource(parsed.origin, "env", parsed.name);
-    const envRoot = path.join(source.path, "env");
-    const envPath = assetPathForName("env", envRoot, parsed.name);
-    // Defense-in-depth: ensure the resolved path stays inside the env directory.
-    // validateName already rejects traversal patterns like "../../foo", but an
-    // absolute-path override or symlink-based attack could still escape without
-    // this second check.
-    if (!isWithin(envPath, envRoot)) {
-        throw new UsageError(`Env name "${parsed.name}" escapes the env directory.`);
-    }
-    return { name: parsed.name, absPath: envPath, source, parsedRef: parsed, dir: "env" };
+    const conceptId = conceptIdFromTypeName("env", parsed.name);
+    const match = findEnvSecretOwner(parsed.origin, conceptId);
+    if (!match)
+        throw new NotFoundError(`Env not found: ${makeBundleRef(parsed.origin, conceptId)}`);
+    return {
+        name: parsed.name,
+        absPath: match.owner.path,
+        source: match.source,
+        bundleId: match.bundleId,
+        parsedRef: parsed,
+        dir: "env",
+    };
 }
 export function parseSecretRef(ref) {
-    // Same bare-name-vs-full-ref rule as parseEnvRef; a bare name is qualified
-    // with the `secrets/` conceptId prefix (secret's stash subdir).
-    return parseRefInput(isFullRefInput(ref) ? ref : `secrets/${ref}`);
+    return parseTypedRef(ref, "secret", "secrets/<name>");
 }
 export function makeSecretRef(name, source) {
     // F4b output-spelling flip: `secrets/name` in the primary stash,
@@ -149,39 +180,22 @@ function displayDefaultBundle(source, config = loadConfig()) {
     const primary = resolveSourceEntries(undefined, config)[0];
     return primary && path.resolve(primary.path) === path.resolve(source.path) ? source.registryId : undefined;
 }
-export function resolveSecretPath(ref, 
-// Create-only (`secret set`): enforce a flat ref name and apply `--path` as
-// the subdirectory. Lookup callers omit this so nested refs keep resolving.
-create) {
+export function resolveSecretPath(ref) {
     const parsed = parseSecretRef(ref);
-    if (parsed.type !== "secret") {
-        throw new UsageError(`Expected a secret ref (secrets/<name>); got "${ref}".`);
-    }
-    if (create) {
-        assertFlatAssetName(parsed.name);
-        parsed.name = combineCreatePath(normalizeCreateSubPath(create.subPath), parsed.name);
-    }
-    // Source resolution is identical for every asset type; reuse the env helper.
-    const source = findEnvSource(parsed.origin, "secret", parsed.name);
-    const typeRoot = path.join(source.path, "secrets");
-    const absPath = assetPathForName("secret", typeRoot, parsed.name);
-    // Defense-in-depth: ensure the resolved path stays inside the secrets dir.
-    if (!isWithin(absPath, typeRoot)) {
-        throw new UsageError(`Secret name "${parsed.name}" escapes the secrets directory.`);
-    }
-    return { name: parsed.name, absPath, source };
+    const conceptId = conceptIdFromTypeName("secret", parsed.name);
+    const match = findEnvSecretOwner(parsed.origin, conceptId);
+    if (!match)
+        throw new NotFoundError(`Secret not found: ${makeBundleRef(parsed.origin, conceptId)}`);
+    return { name: parsed.name, absPath: match.owner.path, source: match.source };
 }
 /**
  * Resolve the destination for an env mutation. Mirrors {@link resolveEnvPath}
  * but selects the source via {@link resolveWriteTarget} (writability-checked)
- * instead of the read-side {@link findEnvSource}. `create` enforces a flat ref
+ * instead of the read-side {@link resolveEnvPath}. `create` enforces a flat ref
  * name and applies `--path` as the subdirectory (matching `env create`).
  */
 export function resolveEnvWriteTarget(ref, writeTarget, create) {
     const parsed = parseEnvRef(ref);
-    if (parsed.type !== "env") {
-        throw new UsageError(`Expected an env ref (env/<name>); got "${ref}".`);
-    }
     if (create) {
         assertFlatAssetName(parsed.name);
         parsed.name = combineCreatePath(normalizeCreateSubPath(create.subPath), parsed.name);
@@ -199,13 +213,10 @@ export function resolveEnvWriteTarget(ref, writeTarget, create) {
  * Resolve the destination for a secret mutation. Mirrors
  * {@link resolveSecretPath} but selects the source via
  * {@link resolveWriteTarget} (writability-checked) instead of the read-side
- * {@link findEnvSource}.
+ * {@link resolveSecretPath}.
  */
 export function resolveSecretWriteTarget(ref, writeTarget, create) {
     const parsed = parseSecretRef(ref);
-    if (parsed.type !== "secret") {
-        throw new UsageError(`Expected a secret ref (secrets/<name>); got "${ref}".`);
-    }
     if (create) {
         assertFlatAssetName(parsed.name);
         parsed.name = combineCreatePath(normalizeCreateSubPath(create.subPath), parsed.name);

package/dist/core/errors.js

@@ -12,15 +12,16 @@ const CONFIG_HINTS = {
     DATA_DIR_UNREADABLE: "The data directory is not readable by the user running akm. Check its owner and mode, or point AKM_DATA_DIR / XDG_DATA_HOME somewhere this user owns.",
     DATA_DIR_NOT_WRITABLE: "Nothing was recorded. Make the akm data directory writable for this process (for an agent sandbox, add it to the writable paths), or point AKM_DATA_DIR / XDG_DATA_HOME somewhere this user can write, then retry.",
     INDEX_SCHEMA_INCOMPATIBLE: "Run `akm index --full` to rebuild the derived index from the currently materialized sources.",
-    LLM_NOT_CONFIGURED: 'Run `akm setup` or configure an `engines` entry with `kind: "llm"`, then select it with `defaults.llmEngine`.',
+    LLM_NOT_CONFIGURED: "Run `akm setup` to add a connection (an OpenAI-compatible endpoint) or enable a harness; model features need one.",
+    AGENT_NOT_CONFIGURED: "Run `akm setup` to enable a harness or add a connection; agent work needs one.",
+    SELECTION_NOT_CONFIGURED: "Name one that is configured (`akm health` lists them), correct the name, or add it with `akm setup --name <name> --endpoint <url>` (a connection) or `akm setup --harness <name>`.",
     TEST_ISOLATION_MISSING: "Under bun test, when AKM_BUNDLE_DIR is set you MUST also set XDG_DATA_HOME (or AKM_DATA_DIR) and XDG_STATE_HOME (or AKM_STATE_DIR) to temp directories so the test does not touch the developer's real ~/.local/share/akm or ~/.local/state/akm.",
     UNSAFE_STASH_DIR: "Choose a path inside your home directory (e.g. ~/akm) or another empty workspace. The bundle directory cannot be the filesystem root, your home directory itself, or a sensitive system path like /etc, /var, ~/.config, or ~/.ssh.",
     UNKNOWN_IMPROVE_STRATEGY: "Pass one of the listed strategy names to `--strategy`, or define it under `improve.strategies`. Names are case-sensitive.",
-    EXECUTION_NOT_AUTHORIZED: "Change the selected tools or update the machine/user execution policy, then retry.",
-    SECRET_REFERENCE_UNRESOLVED: "Check the secret exists (`akm secret list`) and the name after `secret://` matches, or run `akm secret set <name> <value>` to store it.",
+    SECRET_REFERENCE_UNRESOLVED: "Check the secret exists (`akm secret list`) and the ref inside `${…}` matches it, or run `akm secret set secrets/<name>` to store it.",
     REGISTRY_URL_INVALID: "Registry URLs must be credential-free http(s) URLs. Fix the entry with `akm registry list` / `akm registry add`, or the AKM_REGISTRY_URL / AKM_NPM_REGISTRY variable that supplied it.",
 };
-// Code-review finding: COMPOSITION_INVALID covers several unrelated causes
+// COMPOSITION_INVALID covers several unrelated causes
 // (a rejected with:, a multi-job source, a composition cycle/depth/size
 // violation, an invalid child-output reference). USAGE_HINTS below carries
 // only the with:-rejection text — accurate for every with:-rejection throw
@@ -46,15 +47,11 @@ const USAGE_HINTS = {
     MISSING_REQUIRED_ARGUMENT: "Refs use the form [bundle//]conceptId, e.g. `akm show knowledge/guide.md` or `akm show skills/deploy`.",
     UNKNOWN_COMMAND: "Run `akm --help` to see available commands.",
     UNKNOWN_FLAG: "Run the command with `--help` to see its accepted flags.",
-    // P2b (docs/plans/specs/p2b-input-bindings.md §1.7 A-N5, §7 F-A3): the
-    // "arrives in a later 0.9.x release" promise is gone now that task-call
-    // inputs are implemented. Names the two real rejection causes instead:
-    // (1) a task target that declares no inputs: at all, (2) commands/<ref> /
-    // scripts/<ref>, which are never binding surfaces. F-A3 authorizes this
-    // edit and the matching pinned-string update in
-    // tests/core/errors-usage-hints.test.ts in the same commit.
+    // Names the two real rejection causes: (1) a task target that declares no
+    // inputs: at all, (2) commands/<ref> / scripts/<ref>, which are never binding
+    // surfaces.
     //
-    // Code-review finding: this default is reached ONLY by with:-rejection
+    // This default is reached ONLY by with:-rejection
     // throw sites (the ones above, plus task.ts's noDeclaredInputsError and
     // freeze.ts's resolveStep) — every other
     // COMPOSITION_INVALID throw site (multi-job source, composition
@@ -65,10 +62,7 @@ const USAGE_HINTS = {
     COMPOSITION_INVALID: "Remove the with: block, or target a tasks/<ref> whose source declares inputs: — commands/<ref> and scripts/<ref> steps are not binding surfaces.",
     TASK_SOURCE_INVALID: "Fix the task source at the reported path and line, then re-run.",
     TARGET_REF_INVALID: "Targets are canonical asset refs: `commands/review`, `scripts/build.sh`, `tasks/nightly`, `workflows/release`.",
-    // P4 (docs/plans/specs/p4-deletions-closeout.md §4.1, row B-53, R-R5): the
-    // original hint named `akm workflow validate`, a verb that was never
-    // implemented. Points at the two verbs that actually inspect a workflow
-    // source without executing it.
+    // Points at the two verbs that inspect a workflow source without executing it.
     WORKFLOW_SOURCE_INVALID: "Run `akm lint` to see the failing source location, or `akm workflow plan <ref>` to compile it without writing.",
     INPUT_BINDING_INVALID: "Check the step's with: keys against the target's declared inputs.",
     TASK_TARGET_UNSUPPORTED: "Task definitions support command, script, workflow, and shell (run:) targets; akm/command is layered by callers.",

package/dist/core/extra-params.js

@@ -31,7 +31,7 @@ const CREDENTIAL_KEYS = new Set(EXTRA_PARAMS_CREDENTIAL_KEYS);
 // shadowing an AKM-managed field, but naming the rule without naming the fix
 // leaves the reader stuck (#852). Every protected key gets a one-line remedy
 // baked into its issue message.
-/** normalizeExtraParamKey(key) -> the first-class engine field it shadows. */
+/** normalizeExtraParamKey(key) -> the first-class setting it shadows. */
 const LEGACY_EXTRA_PARAMS_FIELD = {
     model: "model",
     temperature: "temperature",
@@ -45,13 +45,13 @@ const EXTRA_PARAMS_NO_FIELD_REMEDY = {
     responseformat: "AKM controls the response format internally — remove it from extraParams",
     stream: "AKM controls streaming internally — remove it from extraParams",
     streamoptions: "AKM controls streaming internally — remove it from extraParams",
-    chattemplatekwargs: "set engines.<name>.enableThinking instead of chat_template_kwargs.enable_thinking",
+    chattemplatekwargs: "set enableThinking instead of chat_template_kwargs.enable_thinking",
 };
 function protectedKeyRemedy(normalized) {
     const field = LEGACY_EXTRA_PARAMS_FIELD[normalized];
     if (field) {
         const note = normalized === "reasoningeffort" ? " (moved to a first-class field in 0.9.2)" : "";
-        return `set engines.<name>.${field} instead${note}`;
+        return `set ${field} instead${note}`;
     }
     return EXTRA_PARAMS_NO_FIELD_REMEDY[normalized];
 }

package/dist/core/improve-result.js

@@ -19,6 +19,7 @@ const COMMON_FIELDS = [
     "plan",
     "actions",
     "skippedProcesses",
+    // No longer written (the retired `--require-engines` probe wrote it); kept readable for envelopes a prior release wrote.
     "engineProbe",
     "distillSkipped",
     "validationFailures",
@@ -30,8 +31,7 @@ const COMMON_FIELDS = [
     "coverageGaps",
     // R10: no longer written (the write-only eval-cases path was removed),
     // but kept in the allow-list so `decodeImproveResult` still reads
-    // improve-result envelopes a prior release wrote with this field —
-    // AGENTS.md "Reading persisted data".
+    // improve-result envelopes a prior release wrote with this field.
     "evalCasesWritten",
     "deadUrls",
     "deadUrlCoverage",
@@ -51,8 +51,7 @@ const COMMON_FIELDS = [
     "reflectGuardRejectedActions",
     // No longer written (nothing has set it since the confidence gate was
     // deleted), but kept in the allow-list so `decodeImproveResult` still reads
-    // the improve_runs rows an older release wrote with it, its value ignored —
-    // AGENTS.md "Reading persisted data".
+    // the improve_runs rows an older release wrote with it, its value ignored.
     "gateAutoAcceptedCount",
     "gateAutoAcceptFailedCount",
     "triage",
@@ -128,7 +127,7 @@ function validateConsolidationPlan(value) {
     if (!isRecord(value.configured))
         fail("plan.consolidation.configured must be an object");
     // `minPoolSize` is no longer written (the minimum-pool guard was removed in 0.10, #1131); runs an
-    // older release persisted still carry it, ignored — AGENTS.md "Reading persisted data".
+    // older release persisted still carry it, ignored.
     requireExactFields(value.configured, new Set(["enabled", "minPoolSize", "limit", "maxChunkSize"]));
     if (value.configured.enabled !== undefined && typeof value.configured.enabled !== "boolean") {
         fail("plan.consolidation.configured.enabled must be a boolean");
@@ -206,7 +205,6 @@ function validateProcessRoutingRows(value) {
     if (!Array.isArray(value))
         fail("plan.processes must be an array");
     const canonicalNames = IMPROVE_PROCESS_NAMES;
-    const engineKinds = new Set(["llm", "agent", "sdk"]);
     const seen = new Set();
     for (const row of value) {
         if (!isRecord(row))
@@ -233,8 +231,9 @@ function validateProcessRoutingRows(value) {
             fail("plan.processes.engine must be a string");
         if (row.model !== undefined && typeof row.model !== "string")
             fail("plan.processes.model must be a string");
-        if (row.engineKind !== undefined && (typeof row.engineKind !== "string" || !engineKinds.has(row.engineKind))) {
-            fail("plan.processes.engineKind is invalid");
+        // "connection" or "harness" now; a run recorded by an earlier release said "llm", "agent" or "sdk".
+        if (row.engineKind !== undefined && typeof row.engineKind !== "string") {
+            fail("plan.processes.engineKind must be a string");
         }
         validateLoweringNotices(row.notices);
         if (row.unavailable !== undefined) {
@@ -409,7 +408,7 @@ function validateImprovePlan(value, dryRun, plannedRefNames) {
     // #947 added plan.processes (2026-09-09T09:03:19Z); every run recorded
     // before it legitimately stored `plan` with no `processes` key at all —
     // validate the rows only when present, same as `proactive` below, so a
-    // pre-#947 envelope still decodes (AGENTS.md "Reading persisted data").
+    // pre-#947 envelope still decodes.
     if (value.processes !== undefined)
         validateProcessRoutingRows(value.processes);
     if (value.proactive !== undefined)

package/dist/core/json-schema.js

@@ -41,7 +41,7 @@
  * branching multiplies work by schema size, never exponentially.
  *
  * Returns a flat list of human-readable error strings (empty = valid), each
- * prefixed with a JSON-pointer-ish path — the shape `runStructured`'s
+ * prefixed with a JSON-pointer-ish path — the shape the structured loop's
  * corrective-feedback builder wants.
  *
  * {@link checkJsonSchemaDefinition} is the companion DEFINITION checker: it

package/dist/core/lesson-lint.js

@@ -2,7 +2,7 @@
 // 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/.
 /**
- * Deterministic frontmatter lint for `lesson` assets (v1 spec §13).
+ * Deterministic frontmatter lint for `lesson` assets.
  *
  * The contract is fixed:
  *

package/dist/core/llm-inference.js

@@ -0,0 +1,80 @@
+// 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 { isPlainObject } from "./config/deep-merge.js";
+import { warnOnce } from "./warn.js";
+/**
+ * The portable settings a request's inference may carry and an endpoint's
+ * request translates: `temperature`, `maxTokens`, `reasoningEffort` (an asset's
+ * `effort:` is the same setting) and `enableThinking`, plus `extraParams`, whose
+ * entries are inlined as request fields. `contextLength` is a connection's own
+ * key, not a per-call setting.
+ */
+export const PORTABLE_INFERENCE_KEYS = [
+    "temperature",
+    "maxTokens",
+    "reasoningEffort",
+    "enableThinking",
+    "extraParams",
+];
+/** Whether a request's fields turn thinking on or off, in either of the two spellings an endpoint reads; `undefined` when they say nothing. */
+export function thinkingSetting(request) {
+    const kwargs = request.chat_template_kwargs;
+    const nested = typeof kwargs === "object" && kwargs !== null ? kwargs.enable_thinking : undefined;
+    const value = request.enable_thinking ?? nested;
+    return typeof value === "boolean" ? value : undefined;
+}
+/** The wire fields for `inference`, in the order the request lists them. */
+export function inferenceWireFields(inference) {
+    if (!inference)
+        return {};
+    return {
+        ...(inference.temperature !== undefined ? { temperature: inference.temperature } : {}),
+        ...(inference.maxTokens !== undefined ? { max_tokens: inference.maxTokens } : {}),
+        ...inference.extraParams,
+        // Which of the two thinking fields an endpoint honors is a fact about it (and any gateway in
+        // front of it), not about akm's wording: send both whenever thinking is set.
+        ...(inference.enableThinking !== undefined
+            ? {
+                chat_template_kwargs: { enable_thinking: inference.enableThinking },
+                enable_thinking: inference.enableThinking,
+            }
+            : {}),
+        ...(inference.reasoningEffort !== undefined ? { reasoning_effort: inference.reasoningEffort } : {}),
+    };
+}
+/**
+ * `over` laid on `base`, one level deep: a field that is an object on both sides
+ * (`chat_template_kwargs`) is merged key by key, so a call's `enableThinking`
+ * does not erase the `thinking_budget` beside it; any other field of `over` wins.
+ */
+export function mergeRequestFields(base, over) {
+    const merged = { ...base };
+    for (const [key, value] of Object.entries(over)) {
+        const was = merged[key];
+        merged[key] = isPlainObject(was) && isPlainObject(value) ? { ...was, ...value } : value;
+    }
+    return merged;
+}
+/**
+ * The fields of a request that are not the user's to set: the model akm resolved, the conversation and tool
+ * state the transport builds, whether the reply streams, and the response format the caller asks for. Whichever
+ * way one is written (a connection or model entry's request fields, or an `extraParams` of a call, a process or
+ * a workflow step) it is ignored for that field, on both transports.
+ */
+export const OWNED_REQUEST_FIELDS = ["model", "messages", "tools", "stream", "response_format"];
+function withoutOwnedFields(request) {
+    const written = OWNED_REQUEST_FIELDS.filter((field) => Object.hasOwn(request, field));
+    if (written.length === 0)
+        return request;
+    warnOnce(`request-fields:owned:${written.join(",")}`, `Request field${written.length === 1 ? "" : "s"} ${written.map((field) => `"${field}"`).join(", ")} in a connection's or model entry's request fields, or in an extraParams, ${written.length === 1 ? "is" : "are"} ignored: akm sets the model, the conversation, the tools, streaming and the response format itself.`);
+    return Object.fromEntries(Object.entries(request).filter(([field]) => !OWNED_REQUEST_FIELDS.includes(field)));
+}
+/**
+ * The fields a request carries: `request` as written, with the translation of `inference` laid on it, less the
+ * fields akm owns, which are taken out of the merged result so no layer can bring one back. The one place
+ * portable settings meet an endpoint's own spelling, and where both transports take the user's fields from.
+ */
+export function effectiveRequestFields(request, inference) {
+    return withoutOwnedFields(mergeRequestFields(request ?? {}, inferenceWireFields(inference ?? undefined)));
+}

package/dist/core/parse.js

@@ -5,8 +5,8 @@
  * Shared JSON parsing utilities for LLM and agent output.
  *
  * Lives in `src/core/` so that both `src/llm/` and `src/integrations/agent/`
- * can import without crossing the one-way boundary defined by v1 spec §9.7
- * (agent/ must not import from llm/).
+ * can import without crossing the one-way boundary (agent/ must not import
+ * from llm/).
  *
  * The canonical implementation is ported from `src/llm/client.ts` (most
  * complete version):

package/dist/core/paths.js

@@ -311,12 +311,7 @@ export function getStateDir(env = process.env, platform = process.platform) {
  * its `stash_dir` column — so two stashes on one machine never collide.
  *
  * Reuses {@link shortHash} (bundle-id.ts) rather than growing a second
- * sha256-truncated-hex helper. (The other existing option,
- * `getCurrentWorkflowScopeKey`'s `dir:v1:<sha256>` in
- * `src/workflows/authoring/scope-key.ts`, is a state.db column value for a
- * different subsystem — full untruncated hex plus a `dir:v1:` prefix, which
- * is neither filesystem-safe as a directory segment on Windows (`:`) nor
- * short, so it is not a fit here.) `shortHash` trims to 8 hex chars (32
+ * sha256-truncated-hex helper. `shortHash` trims to 8 hex chars (32
  * bits) — fine at its original call site because a collision only ever
  * shortens a batch-unique slug suffix that a retry loop immediately
  * re-disambiguates. Here there is no such retry loop, but a machine
@@ -348,7 +343,38 @@ export function getUnresolvedSourcesDir(stashDir) {
 export function getStashLocksDir(stashDir) {
     return stashScopedDir(path.join(getStateDir(), "locks"), stashDir);
 }
-// ── Scheduled-task runtime directories (logs + history) ──────────────────────
+/**
+ * The directories this akm resolved, as the `AKM_*` variables that name them, so a
+ * child that runs `akm` (an exec unit, an agent CLI) uses the same installation even
+ * when the parent found them through `XDG_*_HOME`. `AKM_BUNDLE_DIR` is passed only
+ * when the parent set one.
+ */
+export function akmLocations() {
+    const locations = {
+        AKM_CONFIG_DIR: getConfigDir(),
+        AKM_DATA_DIR: getDataDir(),
+        AKM_CACHE_DIR: getCacheDir(),
+        AKM_STATE_DIR: getStateDir(),
+    };
+    const bundleDir = process.env.AKM_BUNDLE_DIR?.trim();
+    if (bundleDir)
+        locations.AKM_BUNDLE_DIR = bundleDir;
+    return locations;
+}
+/**
+ * The environment of a process akm starts for the user: akm's own, as the program
+ * has it when the user runs it from their shell, with {@link akmLocations} set over
+ * it. akm filters nothing.
+ */
+export function childProcessEnv() {
+    const inherited = {};
+    for (const [name, value] of Object.entries(process.env)) {
+        if (value !== undefined)
+            inherited[name] = value;
+    }
+    return { ...inherited, ...akmLocations() };
+}
+// ── Scheduled-task runtime directory (logs; run history lives in state.db) ───
 export function getTaskLogDir() {
     return path.join(getCacheDir(), "tasks", "logs");
 }
@@ -356,9 +382,6 @@ export function getTaskLogDir() {
 export function getRunLogDir(kind) {
     return path.join(getCacheDir(), "logs", kind);
 }
-export function getTaskHistoryDir() {
-    return path.join(getCacheDir(), "tasks", "history");
-}
 // ── Default stash directory ──────────────────────────────────────────────────
 export function getDefaultStashDir(env = process.env) {
     const override = env.AKM_BUNDLE_DIR?.trim();

package/dist/core/recognition-util.js

@@ -68,16 +68,14 @@ export const DERIVED_SUFFIX = ".derived";
 // compile if a key is missing). A plain `as const` literal tuple adds no
 // import, so it lives here without breaking the D1-5 import-free invariant.
 /**
- * The AKM-owned built-in asset type keys — the deleted `common.ts` `ASSET_TYPES`
- * set (same order) minus the retired `wiki` type (chunk 4); `instruction`
- * (CLAUDE.md / AGENTS.md project-instruction files) is the newest, added for the
- * format-family adapters (spec §6/§7 instruction row, maintainer resolution
- * 2026-07). An instruction file is a read-like-knowledge markdown document, so
- * it reuses knowledge's presentation shape (label "Instruction", `knowledge-md`
- * renderer, a "read the project instructions" action) rather than the generic
- * fallback. `wiki` was removed here in chunk 4 ("the wiki ASSET-TYPE dies", plan
- * §11 Chunk 4 / §7.4): the LLM Wiki structure now lives in the first-class
- * `llm-wiki` adapter whose page kinds are open (foreign) types, not AKM-owned.
+ * The AKM-owned built-in asset type keys. `instruction`
+ * (CLAUDE.md / AGENTS.md project-instruction files) is the one added for the
+ * format-family adapters: an instruction file is a read-like-knowledge
+ * markdown document, so it reuses knowledge's presentation shape (label
+ * "Instruction", `knowledge-md` renderer, a "read the project instructions"
+ * action) rather than the generic fallback. `wiki` is not an AKM-owned type:
+ * the LLM Wiki structure lives in the first-class `llm-wiki` adapter whose
+ * page kinds are open (foreign) types.
  */
 export const KNOWN_TYPES = [
     "skill",