akm-cli 0.10.261012-beta → 0.10.261014-beta

package/dist/indexer/search/db-search.js

@@ -19,6 +19,7 @@ import { withStateDbTelemetry } from "../../core/state-db.js";
 import { systemErrorCode } from "../../core/system-error.js";
 import { presentationFor } from "../../core/type-presentation.js";
 import { embed } from "../../llm/embedder.js";
+import { effectiveEmbedding } from "../../llm/embedders/connection.js";
 import { applyEmbeddingTemplate, resolveEmbeddingProfile } from "../../llm/embedders/profile.js";
 import { normalizeEmbeddingEndpoint } from "../../llm/embedders/remote.js";
 import { assertIndexPathReadable, closeDatabase, openExistingDatabase, openReadonlyExistingDatabase, } from "../../storage/repositories/index-connection.js";
@@ -400,7 +401,7 @@ export function applyEntryFilters(items, opts) {
     const scopeFiltered = filters
         ? sourceFiltered.filter((item) => entryMatchesScope(item.entry.scope, filters))
         : sourceFiltered;
-    // Proposed-quality filter (v1 spec §4.2): exclude `quality: "proposed"`
+    // Proposed-quality filter: exclude `quality: "proposed"`
     // entries unless the caller opts in.
     const qualityFiltered = opts.includeProposed
         ? scopeFiltered
@@ -469,7 +470,8 @@ function startVectorChannel(db, query, config, filterCandidates) {
     // a live warning instead of silently skipping with no signal.
     if (getEmbeddingCount(db) === 0)
         return Promise.resolve({ neighbors: null });
-    const timeoutMs = config.embedding?.queryTimeoutMs ?? DEFAULT_QUERY_EMBED_TIMEOUT_MS;
+    const embedding = effectiveEmbedding(config);
+    const timeoutMs = embedding?.queryTimeoutMs ?? DEFAULT_QUERY_EMBED_TIMEOUT_MS;
     const controller = new AbortController();
     let timer;
     const timeout = new Promise((_, reject) => {
@@ -478,8 +480,8 @@ function startVectorChannel(db, query, config, filterCandidates) {
             reject(new Error(`Query embedding timed out after ${timeoutMs}ms`));
         }, timeoutMs);
     });
-    const queryText = applyEmbeddingTemplate(resolveEmbeddingProfile(config.embedding).queryTemplate, query);
-    return Promise.race([embed(queryText, config.embedding, controller.signal), timeout])
+    const queryText = applyEmbeddingTemplate(resolveEmbeddingProfile(embedding).queryTemplate, query);
+    return Promise.race([embed(queryText, embedding, controller.signal), timeout])
         .then((vector) => ({ neighbors: searchVec(db, vector, CHANNEL_DEPTH, undefined, filterCandidates) }))
         .catch((error) => ({ neighbors: null, warning: buildVectorFallbackWarning(config, error) }))
         .finally(() => clearTimeout(timer));
@@ -489,7 +491,7 @@ function buildVectorFallbackWarning(config, error) {
     const reason = classifyVectorFailure(error);
     const target = endpoint
         ? `embedding endpoint ${endpoint}`
-        : config.embedding?.endpoint
+        : effectiveEmbedding(config)?.endpoint
             ? "configured embedding endpoint"
             : "local embedding model";
     const unavailable = reason === "connection failed" ? `cannot reach ${target}` : `${target} is unavailable`;
@@ -500,7 +502,7 @@ function buildVectorFallbackWarning(config, error) {
  * or fragments into a warning. Invalid authored values fail closed.
  */
 function safeEmbeddingEndpoint(config) {
-    const endpoint = config.embedding?.endpoint;
+    const endpoint = effectiveEmbedding(config)?.endpoint;
     if (!endpoint)
         return undefined;
     try {
@@ -564,7 +566,7 @@ export async function buildDbHit(input) {
         score: input.score,
         ...(input.whyMatched ? { whyMatched: input.whyMatched } : {}),
         ...(estimatedTokens !== undefined ? { estimatedTokens } : {}),
-        // Surface optional quality (v1 spec §4.2). Omitted when entry has
+        // Surface optional quality. Omitted when entry has
         // no `quality` field so payloads stay compact for the common case.
         ...(input.entry.quality ? { quality: input.entry.quality } : {}),
         ...(input.entry.beliefState ? { beliefState: input.entry.beliefState } : {}),

package/dist/indexer/search/search-source.js

@@ -13,6 +13,20 @@ import { lockContentRootFor } from "../../integrations/lockfile.js";
 import { resolveSourceProviderFactory } from "../../sources/provider-factory.js";
 import { ensureWebsiteMirror } from "../../sources/snapshot-fetchers/website-ingest.js";
 // ── Resolution ──────────────────────────────────────────────────────────────
+/**
+ * The working stash read besides the configured bundles: an explicit argument,
+ * else `AKM_BUNDLE_DIR`, else the platform default stash when no `defaultBundle`
+ * is configured. With a `defaultBundle` and no override there is none, because
+ * the configured bundle is the working stash. Throws as `resolveStashDir` does
+ * when the directory is missing.
+ */
+export function implicitStashDir(config, overrideStashDir) {
+    if (overrideStashDir !== undefined)
+        return path.resolve(overrideStashDir);
+    if (process.env.AKM_BUNDLE_DIR?.trim())
+        return resolveStashDir();
+    return config.defaultBundle ? undefined : resolveStashDir();
+}
 /**
  * Build the ordered list of stash sources, walking every configured stash
  * once. Iteration order:
@@ -29,21 +43,16 @@ import { ensureWebsiteMirror } from "../../sources/snapshot-fetchers/website-ing
 export function resolveSourceEntries(overrideStashDir, existingConfig) {
     const config = existingConfig ?? loadConfig();
     const configuredEntries = bundlesToSourceEntries(config) ?? [];
-    const envOverride = process.env.AKM_BUNDLE_DIR?.trim();
-    const implicitStashDir = overrideStashDir !== undefined
-        ? path.resolve(overrideStashDir)
-        : envOverride
-            ? resolveStashDir()
-            : config.defaultBundle
-                ? undefined
-                : resolveStashDir();
-    const implicitConfiguredBundle = implicitStashDir ? bundleKeyForContentRoot(config, implicitStashDir) : undefined;
+    const implicitStash = implicitStashDir(config, overrideStashDir);
+    const implicitConfiguredBundle = implicitStash ? bundleKeyForContentRoot(config, implicitStash) : undefined;
     if (implicitConfiguredBundle && !isBundleEnabled(config, implicitConfiguredBundle)) {
         throw new ConfigError(`The requested working source is disabled as bundle ${JSON.stringify(implicitConfiguredBundle)}.`, "INVALID_CONFIG_FILE");
     }
     // Explicit and environment overrides stay first. Without either override,
     // the configured default enters through the validated loop below.
-    const sources = implicitStashDir ? [{ path: implicitStashDir, writable: true, isDefault: true }] : [];
+    const sources = implicitStash
+        ? [{ path: implicitStash, writable: true, isDefault: true, type: "filesystem" }]
+        : [];
     const sourceIdentity = (dir) => {
         const resolved = path.resolve(dir);
         try {
@@ -53,7 +62,7 @@ export function resolveSourceEntries(overrideStashDir, existingConfig) {
             return resolved;
         }
     };
-    const seen = new Set(implicitStashDir ? [sourceIdentity(implicitStashDir)] : []);
+    const seen = new Set(implicitStash ? [sourceIdentity(implicitStash)] : []);
     const addSource = (dir, registryId, writable, type, adapterId, unresolved = false, isDefault = false) => {
         const resolved = path.resolve(dir);
         const identity = sourceIdentity(resolved);
@@ -65,7 +74,7 @@ export function resolveSourceEntries(overrideStashDir, existingConfig) {
             // identity-less and a user-named primary source ("name": "my-stash")
             // would validate but match zero entries when filtering.
             const existing = sources.find((source) => sourceIdentity(source.path) === identity);
-            if (existing && existing.type === undefined) {
+            if (existing && existing.registryId === undefined) {
                 if (registryId)
                     existing.registryId = registryId;
                 if (isDefault)
@@ -92,7 +101,7 @@ export function resolveSourceEntries(overrideStashDir, existingConfig) {
             ...(unresolved ? { unresolved: true } : {}),
         });
     };
-    // 0.9.0 shape (spec §10.1 / D-R5): resolve from `bundles` + `defaultBundle`.
+    // Resolve from `bundles` + `defaultBundle`.
     // `bundlesToSourceEntries` returns the configured default first, then map
     // insertion order. Each entry is validated before insertion so a component
     // root can never escape its provider's materialized content root.
@@ -102,7 +111,7 @@ export function resolveSourceEntries(overrideStashDir, existingConfig) {
         const component = bundleComponentConfig(config.bundles?.[entry.name ?? ""]);
         const contentRoot = resolveEntryContentDir(entry);
         if (contentRoot == null) {
-            const unresolvedPath = path.join(getUnresolvedSourcesDir(implicitStashDir ?? process.cwd()), entry.name ?? entry.type);
+            const unresolvedPath = path.join(getUnresolvedSourcesDir(implicitStash ?? process.cwd()), entry.name ?? entry.type);
             addSource(unresolvedPath, entry.name, component?.writable ?? resolveWritable(entry), entry.type, component?.adapter, true, entry.name === config.defaultBundle);
             continue;
         }
@@ -124,9 +133,7 @@ export function resolveSourceEntries(overrideStashDir, existingConfig) {
  *
  * Single source of truth: each provider owns its own path. We instantiate the
  * registered {@link import("../../sources/provider.js").SourceProvider} for the entry
- * and call `provider.path()`. This replaces the old per-kind switch ladder
- * (filesystem path / git cache / website cache) that lived here in 0.6.0 —
- * see spec §10 step 4 and §7 "Removed from 0.6.0".
+ * and call `provider.path()`.
  *
  * The git case still does one extra step: the provider returns the cloned
  * repo dir, but the indexer walks the `content/` subdirectory inside it.
@@ -238,20 +245,23 @@ function isSuspiciousStashRoot(dir) {
  * `resolveSourceEntries()` so the content directories pass the
  * `isValidDirectory()` check.
  *
- * `materialize` (default `true`) is the query-time safety valve (spec §14.3 /
- * D11): the sanctioned materialization callers (`akm index`, source
+ * Sources are never refreshed here: `sync()` is called without `force`, so a
+ * source is fetched only when it has never been materialized on this host.
+ * `akm bundle update` is what refreshes one.
+ *
+ * `materialize` (default `true`) is the query-time safety valve: the sanctioned
+ * materialization callers (`akm index`, source
  * add/update/sync, improve's blocking preflight) pass it truthy and clone/pull/
  * fetch as needed. A READ command's inline auto-index passes `materialize:
  * false` — network is FORBIDDEN at query time, so instead of `sync()` we only
  * check whether each cache-backed source is already materialized: a present
- * cache is served as-is (last-known-good; no TTL pull either), while an absent
+ * cache is served as-is (last-known-good), while an absent
  * or partially-staged cache makes that source UNAVAILABLE for the read and is
  * skipped with one warning naming the remedy. The rest of the command still
  * resolves.
  */
 export async function ensureSourceCaches(config, options) {
     const cfg = config ?? loadConfig();
-    const force = options?.force === true;
     const materialize = options?.materialize !== false;
     const onProgress = options?.onProgress ?? (() => { });
     // Polymorphic refresh: walk every enabled source through its registered
@@ -285,6 +295,16 @@ export async function ensureSourceCaches(config, options) {
             // and writes continue using the lock root.
             continue;
         }
+        if (entry.type === "npm") {
+            // A configured npm bundle with no lock entry has no walkable path (its
+            // provider path is the package spec), and nothing marks it materialized,
+            // so syncing it here would hit the npm registry on every index run and
+            // still leave it unindexed. `akm bundle update` installs it and writes
+            // the lock entry.
+            warn(`Warning: npm source "${entry.name}" is not installed; skipping it. ` +
+                `Run \`akm bundle update ${entry.name}\` to install it.`);
+            continue;
+        }
         const factory = resolveSourceProviderFactory(entry.type);
         if (!factory)
             continue;
@@ -316,7 +336,7 @@ export async function ensureSourceCaches(config, options) {
             // `toSync` only ever holds providers whose `.sync` passed the check
             // above; the optional-chain here is just to satisfy the type (the
             // narrowing does not survive the array round-trip).
-            await provider.sync?.({ force, secrets: options?.secrets, ensureWebsiteMirror });
+            await provider.sync?.({ secrets: options?.secrets, ensureWebsiteMirror });
         }
         catch (err) {
             warn(`Warning: failed to refresh ${provider.kind} source "${provider.name}": ${err instanceof Error ? err.message : String(err)}`);

package/dist/indexer/usage/usage-events.js

@@ -14,9 +14,8 @@ const USAGE_EVENT_SOURCES = new Set(["user", "improve", "task", "audit", "unknow
  * Resolve subprocess provenance without treating an invalid value as user
  * demand.
  *
- * `fallback` (spec docs/plans/specs/p1b-model-extraction.md §5.2, F-1) is what
- * an unset/empty ambient value resolves to — it defaults to `"user"`, which
- * reproduces every pre-P1b call site byte-for-byte (P-07). A caller that
+ * `fallback` is what an unset/empty ambient value resolves to — it defaults to `"user"`.
+ * A caller that
  * already knows the invocation's provenance (the task runner, threading its
  * `ExecutionProvenanceContext`) passes its resolved value as the fallback
  * instead, so a recognized ambient `AKM_EVENT_SOURCE` still wins everywhere it

package/dist/indexer/walk/index-context.js

@@ -1,4 +1,5 @@
 // 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/.
-export {};
+/** The `index_meta` key holding the last index run's {@link SemanticSearchRecord}. */
+export const SEMANTIC_SEARCH_META_KEY = "semanticSearch";

package/dist/indexer/walk/matchers.js

@@ -118,7 +118,6 @@ const ARGUMENTS_PLACEHOLDER_RE = /\$ARGUMENTS/;
 const NUMERIC_PLACEHOLDER_RE = /\$[123](?!\d|[.,]\d)/;
 const SMART_MD_FACTS = {
     workflow: { type: "workflow", specificity: 19 },
-    toolsAgent: { type: "agent", specificity: 20 },
     command: { type: "command", specificity: 18 },
     modelAgent: { type: "agent", specificity: 8 },
     knowledge: { type: "knowledge", specificity: 5 },
@@ -213,22 +212,15 @@ function classifyBySmartMd(ctx) {
     const body = ctx.content();
     const fm = ctx.frontmatter();
     // Recognition is frontmatter `type: workflow` or residence under `workflows/`
-    // (workflow-format-unification, spec §2.5) — no content sniffing. The
+    // — no content sniffing. The
     // directory rule is `classifyByDirectory`/`classifyByParentDirHint`'s job;
     // this only catches a workflow living OUTSIDE `workflows/` that still
     // declares its type explicitly.
     if (fm && fm.type === "workflow") {
         return SMART_MD_FACTS.workflow;
     }
-    if (fm) {
-        // `tools` is the one authoring key for an agent's tool grant. Recognition
-        // covers only the key the renderer honors.
-        if ("tools" in fm) {
-            return SMART_MD_FACTS.toolsAgent;
-        }
-        if ("agent" in fm) {
-            return SMART_MD_FACTS.command;
-        }
+    if (fm && "agent" in fm) {
+        return SMART_MD_FACTS.command;
     }
     // `$ARGUMENTS` is unambiguous, so it keeps its long-standing precedence: a
     // command dropped under `knowledge/` is still found as a command. A skill's

package/dist/indexer/walk/path-resolver.js

@@ -1,55 +1,15 @@
 // 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 fs from "node:fs";
-import path from "node:path";
-import { assetPathForName, stashDirFor } from "../../core/asset/asset-placement.js";
-import { parseRefInput } from "../../core/asset/resolve-ref.js";
-import { isWithin } from "../../core/common.js";
-import { resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
+import { conceptIdFromTypeName, parseRefInput } from "../../core/asset/resolve-ref.js";
 import { lookup } from "../indexer.js";
 import { deriveInstallations } from "../installations.js";
+import { resolveConceptOwner } from "../lookup/adapter-concept-owner.js";
 import { resolveSourceEntries } from "../search/search-source.js";
 function normalizeRef(ref) {
     // String inputs use the current `[bundle//]conceptId` grammar.
     return typeof ref === "string" ? parseRefInput(ref) : ref;
 }
-function buildDiskCandidates(sourcePath, ref, preserveDirectNameFallback) {
-    const placementStashDir = stashDirFor(ref.type);
-    // Opaque adapter conceptIds are index-resolved. Core cannot infer their
-    // adapter-owned serialization or path extension before indexing.
-    if (placementStashDir === undefined)
-        return [];
-    const typeDir = path.join(sourcePath, placementStashDir);
-    const candidates = [
-        assetPathForName(ref.type, typeDir, ref.name),
-        path.join(sourcePath, ref.type, `${ref.name}.md`),
-        path.join(sourcePath, ref.type, ref.name),
-    ];
-    if (preserveDirectNameFallback) {
-        candidates.push(path.join(sourcePath, `${ref.name}.md`), path.join(sourcePath, ref.name));
-    }
-    return candidates;
-}
-function resolveDirectoryEntry(filePath, directoryIndexNames) {
-    let stat;
-    try {
-        stat = fs.statSync(filePath);
-    }
-    catch {
-        return null;
-    }
-    if (stat.isFile())
-        return filePath;
-    if (!stat.isDirectory())
-        return null;
-    for (const indexName of directoryIndexNames) {
-        const candidate = path.join(filePath, indexName);
-        if (fs.existsSync(candidate) && fs.statSync(candidate).isFile())
-            return candidate;
-    }
-    return null;
-}
 async function resolveViaIndex(ref) {
     try {
         const entry = await lookup(ref);
@@ -60,32 +20,17 @@ async function resolveViaIndex(ref) {
     }
 }
 function resolveViaDisk(ref, options) {
-    let sources = resolveSourceEntries(options.stashDir);
-    if (options.honorOrigin !== false) {
-        sources = resolveSourcesForOrigin(ref.origin, sources);
-    }
-    const directoryIndexNames = options.directoryIndexNames ?? ["SKILL.md"];
-    const preserveDirectNameFallback = options.preserveDirectNameFallback ?? true;
-    const installations = deriveInstallations(sources);
-    for (const [index, source] of sources.entries()) {
-        const bundleId = installations[index]?.id;
-        if (options.writableBundleIds && (!bundleId || !options.writableBundleIds.has(bundleId)))
-            continue;
-        const candidates = buildDiskCandidates(source.path, ref, preserveDirectNameFallback);
-        for (const candidate of candidates) {
-            if (!fs.existsSync(candidate))
-                continue;
-            const resolved = resolveDirectoryEntry(candidate, directoryIndexNames);
-            if (!resolved)
-                continue;
-            const resolvedRoot = fs.realpathSync(source.path);
-            const realTarget = fs.realpathSync(resolved);
-            if (!isWithin(realTarget, resolvedRoot))
-                continue;
-            return realTarget;
-        }
-    }
-    return null;
+    const allSources = resolveSourceEntries(options.stashDir);
+    const installations = deriveInstallations(allSources);
+    const sources = options.writableBundleIds
+        ? allSources.filter((_, index) => {
+            const bundleId = installations[index]?.id;
+            return bundleId !== undefined && options.writableBundleIds?.has(bundleId);
+        })
+        : allSources;
+    const bundle = options.honorOrigin !== false ? ref.origin : undefined;
+    return (resolveConceptOwner({ bundle, conceptId: conceptIdFromTypeName(ref.type, ref.name) }, sources)?.owner.realPath ??
+        null);
 }
 export async function resolveAssetPath(ref, options = {}) {
     const parsed = normalizeRef(ref);

package/dist/indexer/walk/walker.js

@@ -11,7 +11,6 @@
 import fs from "node:fs";
 import path from "node:path";
 import { isRelevantAssetFile } from "../../core/asset/asset-placement.js";
-import { WORKFLOW_EXTENSIONS } from "../../core/recognition-util.js";
 import { spawnSync } from "../../runtime.js";
 import { buildFileContext } from "./file-context.js";
 const ALWAYS_SKIP_DIRS = new Set([".git"]);
@@ -60,7 +59,8 @@ export function walkStash(typeRoot, assetType) {
  * Unlike walkStash(), this does NOT filter by asset type or require files to
  * live under type-specific directories. Matchers decide what each file is.
  *
- * If the directory is a git repo, uses `git ls-files` to respect .gitignore.
+ * If the directory is a git repo, uses `git ls-files` to respect .gitignore,
+ * except that git-ignored files under `env/` and `secrets/` are still walked.
  * Otherwise falls back to a manual walk that skips .git, node_modules, bin,
  * .cache, dot-directories, and the legacy metadata sidecar.
  */
@@ -78,7 +78,8 @@ export function walkStashFlatWithStatus(stashRoot, options = {}) {
     return walkStashManual(stashRoot, options);
 }
 /**
- * Walk using `git ls-files` to respect .gitignore.
+ * Walk using `git ls-files` to respect .gitignore (ignored `env/` and
+ * `secrets/` files excepted).
  * Returns null if the directory is not a git repo or git fails.
  */
 function walkStashGit(stashRoot, options) {
@@ -101,12 +102,20 @@ function walkStashGit(stashRoot, options) {
         ? deletedResult.stdout.toString("utf8")
         : String(deletedResult.stdout ?? "");
     const deletedFiles = new Set(deletedStdout.split("\0").filter(Boolean));
+    // `akm bundle create` git-ignores `env/` and `secrets/` so credentials are
+    // never committed, but they are still bundle assets. List the ignored files
+    // under those two directories as well; the adapters index key names only.
+    const ignoredResult = spawnSync(["git", "ls-files", "--others", "--ignored", "--exclude-standard", "-z", "--", "env/", "secrets/"], { cwd: stashRoot });
+    if (!ignoredResult.success)
+        return null;
+    const ignoredStdout = Buffer.isBuffer(ignoredResult.stdout)
+        ? ignoredResult.stdout.toString("utf8")
+        : String(ignoredResult.stdout ?? "");
     // Data-hygiene filename skips: the legacy metadata sidecar (never indexed as
     // content — Chunk-8 folds it into the bundle format) plus git dot-files.
     const SKIP_FILES = new Set([".stash.json", ".gitignore", ".gitattributes"]);
     const stdout = Buffer.isBuffer(result.stdout) ? result.stdout.toString("utf8") : String(result.stdout ?? "");
-    const files = stdout
-        .split("\0")
+    const files = [...stdout.split("\0"), ...ignoredStdout.split("\0")]
         .filter((f) => f.length > 0)
         .filter((f) => !deletedFiles.has(f))
         .filter((f) => !f.startsWith("..") && !path.isAbsolute(f))
@@ -124,13 +133,11 @@ function walkStashGit(stashRoot, options) {
     for (const relFile of files) {
         const absPath = path.join(stashRoot, relFile);
         try {
-            // lstat, not stat: a tracked symlink must not be dereferenced. statSync
-            // follows the link, so a target outside stashRoot would be read and
-            // indexed. The manual walk below already skips symlinks for exactly this
-            // reason; the two walkers have to agree regardless of whether the stash
-            // happens to sit inside a git repo.
+            // A file that is a symlink to a file anywhere is indexed like any other
+            // file: installing a bundle is the trust decision. git lists a symlinked
+            // directory as one entry, so directory symlinks are never descended.
             const stat = fs.lstatSync(absPath);
-            if (stat.isFile() || (stat.isSymbolicLink() && isOwnedWorkflowSymlink(stashRoot, absPath, options))) {
+            if (stat.isFile() || (stat.isSymbolicLink() && isFileOrFileSymlink(absPath))) {
                 results.push(buildFileContext(stashRoot, absPath));
             }
         }
@@ -191,8 +198,11 @@ export function walkMarkdownFiles(root) {
         }
         for (const entry of entries) {
             const full = path.join(current, entry.name);
-            if (entry.isSymbolicLink())
+            if (entry.isSymbolicLink()) {
+                if (entry.name.toLowerCase().endsWith(".md") && isFileOrFileSymlink(full))
+                    files.push(full);
                 continue;
+            }
             if (entry.isDirectory()) {
                 stack.push(full);
             }
@@ -225,11 +235,10 @@ function walkStashManual(stashRoot, options) {
                 continue;
             const fullPath = path.join(current, entry.name);
             if (entry.isSymbolicLink()) {
-                // Native workflow components arbitrate file symlinks explicitly in the
-                // drain before reading them. Directory symlinks remain unfollowed.
-                if (isOwnedWorkflowSymlink(stashRoot, fullPath, options)) {
+                // A file symlink is indexed like any other file; a directory symlink
+                // is never descended (no cycles).
+                if (isFileOrFileSymlink(fullPath))
                     results.push(buildFileContext(stashRoot, fullPath));
-                }
                 continue;
             }
             if (entry.isDirectory()) {
@@ -245,15 +254,12 @@ function walkStashManual(stashRoot, options) {
     }
     return { files: results, complete };
 }
-function isOwnedWorkflowSymlink(stashRoot, candidatePath, options) {
-    const adapterId = options.workflowSymlinkAdapter;
-    if (!adapterId)
-        return false;
-    const relativePath = path.relative(path.resolve(stashRoot), path.resolve(candidatePath)).replaceAll("\\", "/");
-    if (!relativePath || relativePath.startsWith("../") || path.posix.isAbsolute(relativePath))
-        return false;
-    if (adapterId === "akm" && !relativePath.startsWith("workflows/"))
+/** True for a regular file, or a symlink whose target is a regular file. */
+export function isFileOrFileSymlink(filePath) {
+    try {
+        return fs.statSync(filePath).isFile();
+    }
+    catch {
         return false;
-    const extension = path.posix.extname(relativePath).toLowerCase();
-    return WORKFLOW_EXTENSIONS.includes(extension);
+    }
 }

package/dist/integrations/agent/akm-read-tools.js

@@ -0,0 +1,81 @@
+// 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/.
+/**
+ * akm's read-only tools for agent work, in harness-neutral form (#1244): the
+ * `akm` capability. A harness adapts each one to its own tool API; the tool runs
+ * in akm's process and returns what `akm --detail agent <command> --format json`
+ * would print.
+ */
+import { renderOutput } from "../../cli/shared.js";
+import { akmSearch } from "../../commands/read/search.js";
+import { runCurate } from "../../commands/read/search-cli.js";
+import { akmShowUnified } from "../../commands/read/show.js";
+import { loadConfig } from "../../core/config/config.js";
+import { withQuiet } from "../../core/warn.js";
+import { resolveUsageEventSource } from "../../indexer/usage/usage-events.js";
+import { resolveOutputMode } from "../../output/context.js";
+import { stdoutText } from "../../output/stdout.js";
+/** The usage-event source a tool call records: the run's own, validated; the default only for a run with none. */
+const sourceOf = (context) => context?.eventSource === undefined ? undefined : resolveUsageEventSource({ AKM_EVENT_SOURCE: context.eventSource });
+const str = (value) => typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
+const positiveInt = (value) => typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
+/** Run one read command the way the CLI does with `--detail agent --format json`, quietly. */
+function asCli(command, compute) {
+    return withQuiet(async () => {
+        const mode = resolveOutputMode(["--detail", "agent", "--format", "json"], loadConfig().output ?? {});
+        return stdoutText(renderOutput(command, await compute(mode), { ...mode, format: "json" }));
+    });
+}
+function required(input, key) {
+    const value = str(input[key]);
+    if (!value)
+        throw new Error(`"${key}" is required`);
+    return value;
+}
+export const AKM_READ_TOOLS = [
+    {
+        name: "akm_curate",
+        description: "Find the akm assets (skills, knowledge, memories, workflows) that best fit a task. Read one with akm_show before relying on it.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "The task or question" },
+                type: { type: "string", description: "Optional asset type filter" },
+                limit: { type: "integer", minimum: 1 },
+            },
+            required: ["query"],
+        },
+        run: (input, context) => asCli("curate", (mode) => runCurate({
+            query: required(input, "query"),
+            type: str(input.type),
+            limit: positiveInt(input.limit) === undefined ? undefined : String(input.limit),
+            eventSource: sourceOf(context),
+        }, mode)),
+    },
+    {
+        name: "akm_search",
+        description: "Search akm assets by name or keyword.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string" },
+                type: { type: "string", description: "Optional asset type filter" },
+                limit: { type: "integer", minimum: 1 },
+            },
+            required: ["query"],
+        },
+        run: (input, context) => asCli("search", () => akmSearch({
+            query: required(input, "query"),
+            type: str(input.type),
+            limit: positiveInt(input.limit),
+            eventSource: sourceOf(context),
+        })),
+    },
+    {
+        name: "akm_show",
+        description: "Read one akm asset by its ref, as returned by akm_curate or akm_search.",
+        inputSchema: { type: "object", properties: { ref: { type: "string" } }, required: ["ref"] },
+        run: (input, context) => asCli("show", () => akmShowUnified({ ref: required(input, "ref"), eventSource: sourceOf(context) })),
+    },
+];

package/dist/integrations/agent/config.js

@@ -3,5 +3,5 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /** Default agent CLI timeout; null means agents run until they finish. */
 export const DEFAULT_AGENT_TIMEOUT_MS = null;
-/** Default hard timeout for a direct LLM call, and the bound on model work on every runner kind, when no engine/use override exists. */
+/** Default hard timeout for model work (a call on a connection, or model work on a harness) when neither the request nor the connection's or harness's `timeoutMs` sets one. Agent work has none. */
 export const DEFAULT_LLM_TIMEOUT_MS = 600_000;