akm-cli 0.7.5 → 0.8.0-rc2

package/dist/indexer/ranking-contributors.js

@@ -0,0 +1,204 @@
+import { computeGraphBoost } from "./graph-boost";
+const TYPE_BOOST = {
+    skill: 0.4,
+    command: 0.35,
+    workflow: 0.35,
+    agent: 0.3,
+    script: 0.2,
+    knowledge: 0.22,
+    memory: -0.02,
+};
+const MAX_BOOST_SUM = 3.0;
+const UTILITY_WEIGHT = 0.5;
+const UTILITY_MAX_BOOST = 1.5;
+const RECENCY_DECAY_DAYS = 30;
+function beliefStateBoost(item) {
+    const entry = item.entry;
+    if (entry.type !== "memory")
+        return 0;
+    if (entry.beliefState === "contradicted")
+        return -0.45;
+    if (entry.beliefState === "superseded")
+        return -0.25;
+    if (entry.beliefState === "archived")
+        return -0.6;
+    if (entry.beliefState === "active")
+        return 0.06;
+    return 0;
+}
+const exactNameRankingContributor = {
+    name: "exact-name-ranking",
+    appliesTo: () => true,
+    adjust(item, ctx) {
+        const entry = item.entry;
+        const nameLower = entry.name.toLowerCase();
+        const rawNameBase = nameLower.split("/").pop() ?? nameLower;
+        const nameBase = entry.type === "memory" && rawNameBase.endsWith(".derived")
+            ? rawNameBase.slice(0, -".derived".length)
+            : rawNameBase;
+        if (nameBase === ctx.queryLower || nameLower === ctx.queryLower) {
+            return 2.0;
+        }
+        if (nameBase.includes(ctx.queryLower) || ctx.queryLower.includes(nameBase)) {
+            return 1.0;
+        }
+        const nameTokens = nameBase.split(/[-_\s]+/).filter(Boolean);
+        const matchCount = ctx.queryTokens.filter((qt) => nameTokens.some((nt) => nt === qt || nt.includes(qt))).length;
+        return matchCount > 0 ? Math.min(0.9, matchCount * 0.3) : 0;
+    },
+};
+const typeRankingContributor = {
+    name: "type-ranking",
+    appliesTo: () => true,
+    adjust(item) {
+        return TYPE_BOOST[item.entry.type] ?? 0;
+    },
+};
+const memoryRankingContributor = {
+    name: "memory-ranking",
+    appliesTo(item) {
+        return item.entry.type === "memory";
+    },
+    adjust(item) {
+        const derivedBoost = item.entry.name.toLowerCase().endsWith(".derived") ? 0.12 : -0.08;
+        return derivedBoost + beliefStateBoost(item);
+    },
+};
+const tagRankingContributor = {
+    name: "tag-ranking",
+    appliesTo(item) {
+        return Array.isArray(item.entry.tags) && item.entry.tags.length > 0;
+    },
+    adjust(item, ctx) {
+        let tagBoost = 0;
+        for (const tag of item.entry.tags ?? []) {
+            if (ctx.queryTokens.some((token) => tag.toLowerCase() === token))
+                tagBoost += 0.15;
+        }
+        return Math.min(0.3, tagBoost);
+    },
+};
+const searchHintRankingContributor = {
+    name: "search-hint-ranking",
+    appliesTo(item) {
+        return Array.isArray(item.entry.searchHints) && item.entry.searchHints.length > 0;
+    },
+    adjust(item, ctx) {
+        let hintBoost = 0;
+        for (const hint of item.entry.searchHints ?? []) {
+            const hintLower = hint.toLowerCase();
+            for (const token of ctx.queryTokens) {
+                if (hintLower.includes(token)) {
+                    hintBoost += 0.12;
+                    break;
+                }
+            }
+        }
+        return Math.min(0.24, hintBoost);
+    },
+};
+const aliasRankingContributor = {
+    name: "alias-ranking",
+    appliesTo(item) {
+        return Array.isArray(item.entry.aliases) && item.entry.aliases.length > 0;
+    },
+    adjust(item, ctx) {
+        let boost = 0;
+        for (const alias of item.entry.aliases ?? []) {
+            const aliasLower = alias.toLowerCase();
+            if (aliasLower === ctx.queryLower) {
+                boost += 1.5;
+                break;
+            }
+            if (ctx.queryTokens.some((token) => aliasLower.includes(token)))
+                boost += 0.3;
+        }
+        return boost;
+    },
+};
+const descriptionRankingContributor = {
+    name: "description-ranking",
+    appliesTo(item) {
+        return typeof item.entry.description === "string" && item.entry.description.length > 0;
+    },
+    adjust(item, ctx) {
+        const descLower = item.entry.description?.toLowerCase() ?? "";
+        const descMatchCount = ctx.queryTokens.filter((token) => descLower.includes(token)).length;
+        if (descMatchCount === ctx.queryTokens.length && ctx.queryTokens.length > 1)
+            return 0.25;
+        if (descMatchCount > 0)
+            return 0.1;
+        return 0;
+    },
+};
+const metadataRankingContributor = {
+    name: "metadata-ranking",
+    appliesTo: () => true,
+    adjust(item) {
+        let boost = item.entry.quality === "curated" ? 0.05 : 0;
+        if (typeof item.entry.confidence === "number") {
+            boost += Math.min(0.05, Math.max(0, item.entry.confidence) * 0.05);
+        }
+        return boost;
+    },
+};
+const graphRankingContributor = {
+    name: "graph-ranking",
+    appliesTo(_item, ctx) {
+        return ctx.graphContext !== null;
+    },
+    adjust(item, ctx) {
+        return ctx.graphContext ? computeGraphBoost(ctx.graphContext, item.filePath) : 0;
+    },
+};
+const utilityRankingContributor = {
+    name: "utility-ranking",
+    appliesTo(item, ctx) {
+        const utilScore = ctx.utilityScores.get(item.id);
+        return Boolean(utilScore && utilScore.utility > 0);
+    },
+    apply(item, ctx) {
+        const utilScore = ctx.utilityScores.get(item.id);
+        if (!utilScore || utilScore.utility <= 0)
+            return;
+        let recencyFactor = 1;
+        if (utilScore.lastUsedAt) {
+            const lastUsedMs = new Date(utilScore.lastUsedAt).getTime();
+            const daysSinceLastUse = Number.isNaN(lastUsedMs)
+                ? Infinity
+                : Math.max(0, (Date.now() - lastUsedMs) / (1000 * 60 * 60 * 24));
+            recencyFactor = Math.exp(-daysSinceLastUse / RECENCY_DECAY_DAYS);
+        }
+        const rawBoost = 1 + utilScore.utility * recencyFactor * UTILITY_WEIGHT;
+        item.score *= Math.min(rawBoost, UTILITY_MAX_BOOST);
+        item.utilityBoosted = true;
+    },
+};
+export const defaultRankingContributors = [
+    exactNameRankingContributor,
+    typeRankingContributor,
+    memoryRankingContributor,
+    tagRankingContributor,
+    searchHintRankingContributor,
+    aliasRankingContributor,
+    descriptionRankingContributor,
+    metadataRankingContributor,
+    graphRankingContributor,
+];
+export const defaultUtilityRankingContributors = [utilityRankingContributor];
+export function applyScoreContributors(item, ctx, contributors = defaultRankingContributors) {
+    let boostSum = 0;
+    for (const contributor of contributors) {
+        if (!contributor.appliesTo(item, ctx))
+            continue;
+        boostSum += contributor.adjust(item, ctx);
+    }
+    item.score *= 1 + Math.min(boostSum, MAX_BOOST_SUM);
+}
+export function applyUtilityContributors(item, ctx, contributors = defaultUtilityRankingContributors) {
+    for (const contributor of contributors) {
+        if (!contributor.appliesTo(item, ctx))
+            continue;
+        contributor.apply(item, ctx);
+    }
+}

package/dist/indexer/ranking.js

@@ -0,0 +1,74 @@
+import { getUtilityScoresByIds } from "./db";
+import { applyScoreContributors, applyUtilityContributors } from "./ranking-contributors";
+export function normalizeFtsScores(results) {
+    const ftsScoreMap = new Map();
+    if (results.length === 0)
+        return ftsScoreMap;
+    const bestBm25 = results[0].bm25Score;
+    const worstBm25 = results[results.length - 1].bm25Score;
+    const range = bestBm25 - worstBm25;
+    for (const result of results) {
+        const normalized = range !== 0 ? (result.bm25Score - worstBm25) / range : 1.0;
+        const ftsScore = 0.3 + normalized * 0.7;
+        ftsScoreMap.set(result.id, { score: ftsScore, result });
+    }
+    return ftsScoreMap;
+}
+export function combineSearchScores(options) {
+    const FTS_WEIGHT = 0.7;
+    const VEC_WEIGHT = 0.3;
+    const scored = [];
+    const seenIds = new Set();
+    for (const [id, { score: ftsScore, result }] of options.ftsScoreMap) {
+        seenIds.add(id);
+        const embedScore = options.embedScoreMap.get(id);
+        const combinedScore = embedScore !== undefined ? ftsScore * FTS_WEIGHT + embedScore * VEC_WEIGHT : ftsScore;
+        scored.push({
+            id,
+            entry: result.entry,
+            filePath: result.filePath,
+            score: combinedScore,
+            rankingMode: embedScore !== undefined ? "hybrid" : "fts",
+        });
+    }
+    for (const [id, cosine] of options.embedScoreMap) {
+        if (seenIds.has(id))
+            continue;
+        const found = options.getEntryById(id);
+        if (!found)
+            continue;
+        if (options.typeFilter && found.entry.type !== options.typeFilter)
+            continue;
+        scored.push({
+            id,
+            entry: found.entry,
+            filePath: found.filePath,
+            score: cosine * VEC_WEIGHT,
+            rankingMode: "semantic",
+        });
+    }
+    return scored;
+}
+export function applyRankingRules(options) {
+    const queryTokens = options.query.toLowerCase().split(/\s+/).filter(Boolean);
+    const queryLower = options.query.toLowerCase().trim();
+    const rankingContext = {
+        db: options.db,
+        query: options.query,
+        queryLower,
+        queryTokens,
+        graphContext: options.graphContext,
+    };
+    for (const item of options.items) {
+        applyScoreContributors(item, rankingContext);
+    }
+    const utilScoresMap = getUtilityScoresByIds(options.db, options.items.map((item) => item.id));
+    const utilityContext = {
+        ...rankingContext,
+        utilityScores: utilScoresMap,
+    };
+    for (const item of options.items) {
+        applyUtilityContributors(item, utilityContext);
+    }
+    return options.items;
+}

package/dist/indexer/search-hit-enrichers.js

@@ -0,0 +1,22 @@
+import { getRenderer } from "./file-context";
+const rendererSearchHitEnricher = {
+    name: "renderer-search-hit-enricher",
+    appliesTo(ctx) {
+        return ctx.rendererRegistry.rendererNameFor(ctx.type) !== undefined;
+    },
+    async enrich(hit, ctx) {
+        const rendererName = ctx.rendererRegistry.rendererNameFor(ctx.type);
+        if (!rendererName)
+            return;
+        const renderer = await getRenderer(rendererName);
+        renderer?.enrichSearchHit?.(hit, ctx.stashDir);
+    },
+};
+export const defaultSearchHitEnrichers = [rendererSearchHitEnricher];
+export async function enrichSearchHit(hit, ctx, enrichers = defaultSearchHitEnrichers) {
+    for (const enricher of enrichers) {
+        if (!enricher.appliesTo(ctx))
+            continue;
+        await enricher.enrich(hit, ctx);
+    }
+}

package/dist/indexer/search-source.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { resolveStashDir } from "../core/common";
-import { loadConfig } from "../core/config";
+import { getSources, loadConfig } from "../core/config";
 import { resolveSourceProviderFactory } from "../sources/provider-factory";
 // Eager side-effect imports so all built-in source providers self-register
 // before resolveEntryContentDir() runs.
@@ -21,7 +21,7 @@ const GIT_STASH_TYPES = new Set(["git"]);
  *   1. The primary stash directory (the entry marked `primary: true`, or the
  *      legacy top-level `stashDir`). Always emitted, even when the directory
  *      does not yet exist on disk, so callers can use it as the clone target.
- *   2. Each entry in `config.sources ?? config.stashes[]` (in declared order), excluding the
+ *   2. Each entry in `config.sources[]` (in declared order), excluding the
  *      one already emitted as the primary.
  *   3. Each entry in `config.installed[]` (registry-managed stashes).
  *
@@ -32,9 +32,10 @@ const GIT_STASH_TYPES = new Set(["git"]);
 export function resolveSourceEntries(overrideStashDir, existingConfig) {
     const stashDir = overrideStashDir ?? resolveStashDir();
     const config = existingConfig ?? loadConfig();
-    const sources = [{ path: stashDir }];
+    // Primary stash is always writable.
+    const sources = [{ path: stashDir, writable: true }];
     const seen = new Set([path.resolve(stashDir)]);
-    const addSource = (dir, registryId, wikiName) => {
+    const addSource = (dir, registryId, wikiName, writable) => {
         const resolved = path.resolve(dir);
         if (seen.has(resolved))
             return;
@@ -47,13 +48,14 @@ export function resolveSourceEntries(overrideStashDir, existingConfig) {
                 path: resolved,
                 ...(registryId ? { registryId } : {}),
                 ...(wikiName ? { wikiName } : {}),
+                ...(writable ? { writable: true } : {}),
             });
         }
     };
     // (1) + (2) Single pass over declared stashes — primary first if present,
     // then the rest in declared order. The primary's directory is already
     // injected as `sources[0]` above, so we only need to dedupe the source set.
-    const stashes = config.sources ?? config.stashes ?? [];
+    const stashes = getSources(config);
     const primaryIdx = stashes.findIndex((entry) => entry.primary === true);
     const ordered = [];
     if (primaryIdx >= 0) {
@@ -72,11 +74,12 @@ export function resolveSourceEntries(overrideStashDir, existingConfig) {
         const dir = resolveEntryContentDir(entry);
         if (dir == null)
             continue;
-        addSource(dir, entry.name, entry.wikiName);
+        addSource(dir, entry.name, entry.wikiName, entry.writable === true);
     }
     // (3) Installed stashes (registry-managed). Always last.
+    // Only installed entries explicitly marked writable: true are considered writable.
     for (const entry of config.installed ?? []) {
-        addSource(entry.stashRoot, entry.id, entry.wikiName);
+        addSource(entry.stashRoot, entry.id, entry.wikiName, entry.writable === true);
     }
     return sources;
 }
@@ -132,6 +135,19 @@ function resolveEntryContentDir(entry) {
 export function resolveAllStashDirs(overrideStashDir) {
     return resolveSourceEntries(overrideStashDir).map((s) => s.path);
 }
+/**
+ * Return the resolved absolute paths of all writable stash sources.
+ *
+ * The primary stash is always writable. Filesystem/git sources that have
+ * `writable: true` in config are also included. Registry-cached sources
+ * (installed without `writable: true`) are excluded because they are
+ * overwritten on `akm update` and must never be mutated.
+ */
+export function getWritableStashDirs(overrideStashDir, existingConfig) {
+    return resolveSourceEntries(overrideStashDir, existingConfig)
+        .filter((s) => s.writable === true)
+        .map((s) => s.path);
+}
 /**
  * Find which source a file path belongs to.
  */
@@ -226,8 +242,7 @@ function isValidDirectory(dir) {
 export async function ensureSourceCaches(config, options) {
     const cfg = config ?? loadConfig();
     const force = options?.force === true;
-    // Use sources[] (current key) with fallback to stashes[] (deprecated, one-release compat).
-    const entries = cfg.sources ?? cfg.stashes ?? [];
+    const entries = getSources(cfg);
     for (const entry of entries) {
         if (!GIT_STASH_TYPES.has(entry.type) || !entry.url || entry.enabled === false)
             continue;

package/dist/indexer/semantic-status.js

@@ -1,5 +1,5 @@
 import fs from "node:fs";
-import path from "node:path";
+import { writeFileAtomic } from "../core/common";
 import { getCacheDir, getSemanticStatusPath } from "../core/paths";
 import { DEFAULT_LOCAL_MODEL } from "../llm/embedder";
 export function deriveSemanticProviderFingerprint(embedding) {
@@ -41,21 +41,7 @@ export function readSemanticStatus() {
 export function writeSemanticStatus(status) {
     const dir = getCacheDir();
     fs.mkdirSync(dir, { recursive: true });
-    const filePath = getSemanticStatusPath();
-    const tmpPath = path.join(dir, `semantic-status.json.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`);
-    fs.writeFileSync(tmpPath, `${JSON.stringify(status, null, 2)}\n`, "utf8");
-    try {
-        fs.renameSync(tmpPath, filePath);
-    }
-    catch (err) {
-        try {
-            fs.unlinkSync(tmpPath);
-        }
-        catch {
-            /* ignore cleanup failure */
-        }
-        throw err;
-    }
+    writeFileAtomic(getSemanticStatusPath(), `${JSON.stringify(status, null, 2)}\n`);
 }
 export function clearSemanticStatus() {
     try {

package/dist/indexer/walker.js

@@ -136,6 +136,31 @@ function isInsideGitRepo(dir) {
     }
     return false;
 }
+/**
+ * Recursively yield every `.md` file under `root`.
+ *
+ * Shared by graph-extraction and memory-inference so the generator logic
+ * lives in exactly one place. Silently skips directories that cannot be
+ * read (e.g. permission errors).
+ */
+export function* walkMarkdownFiles(root) {
+    let entries;
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const full = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            yield* walkMarkdownFiles(full);
+        }
+        else if (entry.isFile() && entry.name.toLowerCase().endsWith(".md")) {
+            yield full;
+        }
+    }
+}
 /** Manual walk for non-git directories. */
 function walkStashManual(stashRoot) {
     const results = [];

package/dist/integrations/agent/config.js

@@ -27,14 +27,28 @@ import { ConfigError } from "../../core/errors";
 import { warn } from "../../core/warn";
 import { BUILTIN_AGENT_PROFILE_NAMES, getBuiltinAgentProfile, listBuiltinAgentProfiles, } from "./profiles";
 /** Keys recognised at the top level of an `agent` config block. */
-const KNOWN_AGENT_KEYS = new Set(["default", "timeoutMs", "profiles"]);
+const KNOWN_AGENT_KEYS = new Set(["default", "timeoutMs", "profiles", "processes"]);
 /** Keys recognised on a profile entry. */
-const KNOWN_PROFILE_KEYS = new Set(["bin", "args", "stdio", "env", "envPassthrough", "timeoutMs", "parseOutput"]);
+const KNOWN_PROFILE_KEYS = new Set([
+    "bin",
+    "args",
+    "stdio",
+    "env",
+    "envPassthrough",
+    "timeoutMs",
+    "parseOutput",
+    "sdkMode",
+    "model",
+    "endpoint",
+    "apiKey",
+]);
 /**
  * Default hard timeout for an agent CLI. Spec §12.2 calls for a hard
  * timeout; 60s matches the example value in `docs/configuration.md`.
  */
 export const DEFAULT_AGENT_TIMEOUT_MS = 60_000;
+/** Keys recognised on a `processes[<name>]` object entry. */
+const KNOWN_PROCESS_ENTRY_KEYS = new Set(["profile", "timeoutMs"]);
 /**
  * Parse a raw value (typically `rawConfig.agent` from `JSON.parse`) into a
  * normalised {@link AgentConfig}. Returns `undefined` when the value is not
@@ -83,6 +97,11 @@ export function parseAgentConfig(value) {
         if (profiles)
             out.profiles = profiles;
     }
+    if ("processes" in raw) {
+        const processes = parseProcessesMap(raw.processes);
+        if (processes)
+            out.processes = processes;
+    }
     return out;
 }
 function parseAgentProfilesMap(value) {
@@ -98,6 +117,124 @@ function parseAgentProfilesMap(value) {
     }
     return Object.keys(out).length > 0 ? out : undefined;
 }
+/**
+ * Parse one entry in `agent.processes`. Accepts a string (profile name) or an
+ * object with optional `profile` and `timeoutMs` fields. Returns `undefined`
+ * and emits a warning for entries that are neither valid strings nor valid
+ * objects (warn-and-ignore).
+ */
+export function parseProcessEntry(value, name) {
+    if (typeof value === "string") {
+        if (!value.trim()) {
+            warn(`[akm] Ignoring agent.processes."${name}": string value must be non-empty (a profile name).`);
+            return undefined;
+        }
+        return value.trim();
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        warn(`[akm] Ignoring agent.processes."${name}": expected a string (profile name) or an object with optional "profile" and "timeoutMs".`);
+        return undefined;
+    }
+    const raw = value;
+    // Warn on unknown keys (warn-and-ignore contract).
+    for (const key of Object.keys(raw)) {
+        if (!KNOWN_PROCESS_ENTRY_KEYS.has(key)) {
+            warn(`[akm] Ignoring unknown agent.processes."${name}" key: "${key}"`);
+        }
+    }
+    const out = {};
+    if ("profile" in raw) {
+        if (typeof raw.profile === "string" && raw.profile.trim()) {
+            out.profile = raw.profile.trim();
+        }
+        else if (raw.profile !== undefined) {
+            warn(`[akm] Ignoring agent.processes."${name}".profile: expected a non-empty string.`);
+        }
+    }
+    if ("timeoutMs" in raw) {
+        if (raw.timeoutMs === null) {
+            // null = unlimited — explicit, valid.
+            out.timeoutMs = null;
+        }
+        else if (typeof raw.timeoutMs === "number" &&
+            Number.isFinite(raw.timeoutMs) &&
+            Number.isInteger(raw.timeoutMs) &&
+            raw.timeoutMs > 0) {
+            out.timeoutMs = raw.timeoutMs;
+        }
+        else {
+            warn(`[akm] Ignoring agent.processes."${name}".timeoutMs: expected a positive integer (milliseconds) or null (unlimited).`);
+        }
+    }
+    return out;
+}
+/**
+ * Parse the `agent.processes` map. Returns `undefined` when the value is not
+ * a valid object; per-entry validation errors are warn-and-ignored (per spec §9.2).
+ */
+export function parseProcessesMap(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        warn("[akm] Ignoring agent.processes: expected an object.");
+        return undefined;
+    }
+    const out = {};
+    for (const [name, raw] of Object.entries(value)) {
+        const parsed = parseProcessEntry(raw, name);
+        if (parsed !== undefined)
+            out[name] = parsed;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/**
+ * Resolve the agent profile and effective timeout for a named process.
+ *
+ * Resolution order:
+ * 1. `config.processes[processName]` — if a string, that is the profile name;
+ *    if an object, extract `profile` (and optionally `timeoutMs`).
+ * 2. Profile name falls back to `config.default` when not specified in the
+ *    process entry.
+ * 3. `timeoutMs` falls back: `process.timeoutMs` (null = unlimited) →
+ *    profile.timeoutMs → agent.timeoutMs → DEFAULT_AGENT_TIMEOUT_MS.
+ *
+ * Returns `{ profile, timeoutMs }` where `timeoutMs` is `undefined` when the
+ * resolved timeout is `null` (unlimited) or when no timeout is set at any
+ * layer (callers treat `undefined` as the DEFAULT_AGENT_TIMEOUT_MS default).
+ *
+ * Throws {@link ConfigError} (via {@link requireAgentProfile}) when the agent
+ * block is missing or the resolved profile cannot be used.
+ */
+export function resolveProcessAgentProfile(processName, agentConfig) {
+    let profileName;
+    let processTimeoutMs; // null = unlimited from config
+    const processEntry = agentConfig?.processes?.[processName];
+    if (processEntry !== undefined) {
+        if (typeof processEntry === "string") {
+            profileName = processEntry;
+        }
+        else {
+            profileName = processEntry.profile;
+            processTimeoutMs = processEntry.timeoutMs;
+        }
+    }
+    // Profile name falls back to agent.default when not set in the process entry.
+    const resolvedProfile = requireAgentProfile(agentConfig, profileName);
+    // Timeout resolution: process entry → profile → agent-level → undefined (caller applies DEFAULT).
+    let resolvedTimeoutMs;
+    if (processTimeoutMs === null) {
+        // null = explicit "unlimited" — surface as undefined so callers omit the timer.
+        resolvedTimeoutMs = undefined;
+    }
+    else if (processTimeoutMs !== undefined) {
+        resolvedTimeoutMs = processTimeoutMs;
+    }
+    else if (resolvedProfile.timeoutMs !== undefined) {
+        resolvedTimeoutMs = resolvedProfile.timeoutMs;
+    }
+    else if (agentConfig?.timeoutMs !== undefined) {
+        resolvedTimeoutMs = agentConfig.timeoutMs;
+    }
+    return { profile: resolvedProfile, timeoutMs: resolvedTimeoutMs };
+}
 function parseAgentProfileConfig(name, value) {
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
         warn(`[akm] Ignoring agent.profiles."${name}": expected an object.`);
@@ -171,6 +308,30 @@ function parseAgentProfileConfig(name, value) {
     else if (raw.parseOutput !== undefined) {
         warn(`[akm] Ignoring agent.profiles."${name}".parseOutput: expected "text" or "json".`);
     }
+    if (raw.sdkMode === true || raw.sdkMode === false) {
+        out.sdkMode = raw.sdkMode;
+    }
+    else if (raw.sdkMode !== undefined) {
+        warn(`[akm] Ignoring agent.profiles."${name}".sdkMode: expected a boolean.`);
+    }
+    if (typeof raw.model === "string" && raw.model.trim()) {
+        out.model = raw.model.trim();
+    }
+    else if (raw.model !== undefined) {
+        warn(`[akm] Ignoring agent.profiles."${name}".model: expected a non-empty string.`);
+    }
+    if (typeof raw.endpoint === "string" && raw.endpoint.trim()) {
+        out.endpoint = raw.endpoint.trim();
+    }
+    else if (raw.endpoint !== undefined) {
+        warn(`[akm] Ignoring agent.profiles."${name}".endpoint: expected a non-empty string.`);
+    }
+    if (typeof raw.apiKey === "string" && raw.apiKey.trim()) {
+        out.apiKey = raw.apiKey.trim();
+    }
+    else if (raw.apiKey !== undefined) {
+        warn(`[akm] Ignoring agent.profiles."${name}".apiKey: expected a non-empty string.`);
+    }
     return out;
 }
 /**
@@ -184,7 +345,7 @@ function parseAgentProfileConfig(name, value) {
  */
 export function resolveAgentProfile(name, overrides) {
     const builtin = getBuiltinAgentProfile(name);
-    if (!builtin && !overrides?.bin)
+    if (!builtin && !overrides?.bin && overrides?.sdkMode !== true)
         return undefined;
     const base = builtin ??
         {
@@ -208,6 +369,10 @@ export function resolveAgentProfile(name, overrides) {
             : base.envPassthrough,
         timeoutMs: overrides.timeoutMs ?? base.timeoutMs,
         parseOutput: overrides.parseOutput ?? base.parseOutput,
+        sdkMode: overrides.sdkMode ?? base.sdkMode,
+        model: overrides.model ?? base.model,
+        endpoint: overrides.endpoint ?? base.endpoint,
+        apiKey: overrides.apiKey ?? base.apiKey,
     };
     return merged;
 }
@@ -274,6 +439,13 @@ export function requireAgentProfile(agent, requested) {
     if (!profile) {
         throw new ConfigError(`agent profile "${name}" is not built-in and has no \`bin\` override.`, "INVALID_CONFIG_FILE", `Define agent.profiles."${name}".bin in config.json, or pick one of: ${listAgentProfileNames(agent).join(", ")}.`);
     }
+    // Apply the top-level agent.timeoutMs as the effective default for this
+    // profile when the profile itself has no timeout override. This makes
+    // `agent.timeoutMs` the universal fallback without requiring every
+    // profile definition in config.json to repeat it.
+    if (profile.timeoutMs === undefined && agent?.timeoutMs !== undefined) {
+        return { ...profile, timeoutMs: agent.timeoutMs };
+    }
     return profile;
 }
 /**