akm-cli 0.9.1 → 0.9.2-alpha.2

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

@@ -3,12 +3,12 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
-import { isSourceWriteActivated } from "../../core/activation-policy.js";
 import { isWithin, resolveStashDir } from "../../core/common.js";
 import { bundleComponentConfig, bundlesToSourceEntries, getSources, loadConfig } from "../../core/config/config.js";
 import { resolveGitContentRoot, resolveWritable } from "../../core/write-source.js";
 import { lockContentRootFor } from "../../integrations/lockfile.js";
 import { resolveSourceProviderFactory } from "../../sources/provider-factory.js";
+import { ensureWebsiteMirror } from "../../sources/snapshot-fetchers/website-ingest.js";
 // Eager side-effect imports so all built-in source providers self-register
 // before resolveEntryContentDir() runs.
 import "../../sources/providers/index.js";
@@ -22,9 +22,8 @@ import { warn } from "../../core/warn.js";
  *   2. The configured `defaultBundle`, after component-root validation.
  *   3. Remaining configured bundles in installation-priority order.
  *
- * Replaces the previous four-pass loop that walked `stashes[]` separately
- * for each provider kind. Disabled entries (`enabled: false`) are filtered
- * after deduplication. Missing configured roots remain in the result so the
+ * Disabled entries (`enabled: false`) are filtered after deduplication.
+ * Missing configured roots remain in the result so the
  * indexer can classify their scan as incomplete instead of mistaking them for
  * removed sources.
  */
@@ -126,8 +125,8 @@ export function resolveEntryContentDir(entry) {
     // and writes agree on where content is); the localRoot is the already-walkable
     // content root (installed sources are extracted to their content dir), so no
     // content/-subdir step is applied. Fall back to the provider path logic when no
-    // lock entry exists (e.g. a git bundle migrated from a `sources[]` url, whose
-    // provider re-derives the mirror path).
+    // lock entry exists (for example while a configured source is being
+    // materialized for the first time).
     const localRoot = lockContentRootFor(entry.name, entry.type);
     if (localRoot != null)
         return localRoot;
@@ -165,14 +164,6 @@ export function resolveEntryContentDir(entry) {
 export function resolveAllStashDirs(overrideStashDir) {
     return resolveSourceEntries(overrideStashDir).map((s) => s.path);
 }
-/**
- * Return the resolved absolute paths of all writable stash sources.
- */
-export function getWritableStashDirs(overrideStashDir, existingConfig) {
-    return resolveSourceEntries(overrideStashDir, existingConfig)
-        .filter((s) => isSourceWriteActivated(s))
-        .map((s) => s.path);
-}
 /**
  * Find which source a file path belongs to.
  *
@@ -263,7 +254,7 @@ export async function ensureSourceCaches(config, options) {
     // provider and call `sync()`. Every cache-backed kind (git, website, npm)
     // refreshes the same way — a bad source warns and is skipped without
     // aborting the others. The git content/-subdir layout convention stays in
-    // resolveEntryContentDir. NEW shape reads `bundles`; old shape reads sources[].
+    // resolveEntryContentDir. Provider projection comes only from `bundles`.
     //
     // DISTINCTION (deliberately NOT lock-first): refresh derives the PROVIDER's
     // own cache path to git-pull/re-materialize INTO — that derived path is where
@@ -304,7 +295,7 @@ export async function ensureSourceCaches(config, options) {
             continue;
         }
         try {
-            await provider.sync({ force, secrets: options?.secrets });
+            await provider.sync({ force, 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/search/semantic-status.js

@@ -6,6 +6,11 @@ import { writeFileAtomic } from "../../core/common.js";
 import { getCacheDir, getSemanticStatusPath } from "../../core/paths.js";
 import { DETERMINISTIC_EMBED_MODEL_ID, isDeterministicEmbedEnabled } from "../../llm/embedders/deterministic.js";
 import { DEFAULT_LOCAL_MODEL } from "../../llm/embedders/local.js";
+let semanticStatusMutationForTests;
+/** TEST-ONLY. Inject a semantic-status filesystem publication fault. */
+export function _setSemanticStatusMutationForTests(mutation) {
+    semanticStatusMutationForTests = mutation;
+}
 export function deriveSemanticProviderFingerprint(embedding) {
     if (isDeterministicEmbedEnabled()) {
         return `deterministic:${DETERMINISTIC_EMBED_MODEL_ID}`;
@@ -49,11 +54,13 @@ export function readSemanticStatus() {
     return undefined;
 }
 export function writeSemanticStatus(status) {
+    semanticStatusMutationForTests?.("write");
     const dir = getCacheDir();
     fs.mkdirSync(dir, { recursive: true });
     writeFileAtomic(getSemanticStatusPath(), `${JSON.stringify(status, null, 2)}\n`);
 }
 export function clearSemanticStatus() {
+    semanticStatusMutationForTests?.("clear");
     try {
         fs.unlinkSync(getSemanticStatusPath());
     }
@@ -110,7 +117,9 @@ export function classifySemanticFailure(message) {
     if (lower.includes("404") || lower.includes("model not found") || lower.includes("bad request")) {
         return "remote-model";
     }
-    if (lower.includes("transformers") || lower.includes("missing-package")) {
+    if (lower.includes("transformers") ||
+        lower.includes("missing-package") ||
+        lower.includes("local embedding dependency is unavailable")) {
         return "missing-package";
     }
     if (lower.includes("download")) {

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

@@ -0,0 +1,105 @@
+// 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 { makeBundleRef, parseBundleRef } from "../../core/asset/asset-ref.js";
+import { rethrowIfTestIsolationError } from "../../core/errors.js";
+import { appendEvent, readEvents } from "../../core/events.js";
+import { withStateDbTelemetry } from "../../core/state-db.js";
+import { TELEMETRY_BUSY_TIMEOUT_MS, withIndexDb } from "../../storage/repositories/index-db.js";
+import { findEntryIdByRef, getEntryById, getEntryIdByFilePath, getItemRefById, } from "../../storage/repositories/index-entries-repository.js";
+import { usageEventAttributionMetadata } from "../search/search-attribution.js";
+import { insertUsageEvent } from "./usage-events.js";
+/** Count prior show events in the current one-hour loop-detection window. */
+export function recentShowCount(ref) {
+    try {
+        return readEvents({
+            type: "show",
+            ref,
+            since: new Date(Date.now() - 60 * 60 * 1000).toISOString(),
+        }).events.length;
+    }
+    catch {
+        return 0;
+    }
+}
+function appendShowTrace(ref, type, name) {
+    appendEvent({ eventType: "show", ref, metadata: { type, name } });
+    try {
+        const { events: recentSearches } = readEvents({
+            type: "search",
+            since: new Date(Date.now() - 60_000).toISOString(),
+        });
+        const cutoffMs = Date.now() - 60_000;
+        const matchingSearch = [...recentSearches].reverse().find((event) => {
+            if (!event.ts || new Date(event.ts).getTime() < cutoffMs)
+                return false;
+            const refs = event.metadata?.resultRefs ?? [];
+            return refs.includes(ref);
+        });
+        if (!matchingSearch)
+            return;
+        const resultRefs = matchingSearch.metadata?.resultRefs ?? [];
+        appendEvent({
+            eventType: "select",
+            ref,
+            metadata: {
+                query: matchingSearch.metadata?.query,
+                searchTs: matchingSearch.ts,
+                rankPosition: resultRefs.indexOf(ref),
+            },
+        });
+    }
+    catch {
+        // Selection attribution is best-effort.
+    }
+}
+function insertShowUsage(entryId, entryRef, derivedFrom, eventSource) {
+    withStateDbTelemetry((stateDb) => {
+        insertUsageEvent(stateDb, {
+            event_type: "show",
+            entry_ref: entryRef,
+            entry_id: entryId,
+            metadata: usageEventAttributionMetadata(derivedFrom ? { memoryInference: { exposure: "direct" } } : undefined, entryRef),
+            source: eventSource,
+        });
+    }, TELEMETRY_BUSY_TIMEOUT_MS);
+}
+/** Record a successful show using the already-rendered response identity. */
+export function recordShowUsage(ref, type, name, eventSource = "user", filePath) {
+    const parsed = parseBundleRef(ref);
+    const eventRef = makeBundleRef(parsed.bundle, parsed.conceptId);
+    appendShowTrace(eventRef, type, name);
+    try {
+        withIndexDb((db) => {
+            const entryId = filePath ? getEntryIdByFilePath(db, filePath) : findEntryIdByRef(db, eventRef);
+            if (entryId === undefined)
+                return;
+            const entryRef = getItemRefById(db, entryId);
+            if (!entryRef)
+                return;
+            insertShowUsage(entryId, entryRef, getEntryById(db, entryId)?.entry.derivedFrom, eventSource);
+        }, { busyTimeoutMs: TELEMETRY_BUSY_TIMEOUT_MS });
+    }
+    catch (error) {
+        rethrowIfTestIsolationError(error);
+    }
+}
+/** Record a nested execution-source read only after dispatch has crossed preflight. */
+export function recordIndexedShowUsage(ref, eventSource = "user") {
+    try {
+        withIndexDb((db) => {
+            const entryId = findEntryIdByRef(db, ref);
+            if (entryId === undefined)
+                return;
+            const indexed = getEntryById(db, entryId);
+            const entryRef = getItemRefById(db, entryId);
+            if (!indexed || !entryRef)
+                return;
+            appendShowTrace(entryRef, indexed.entry.type, indexed.entry.name);
+            insertShowUsage(entryId, entryRef, indexed.entry.derivedFrom, eventSource);
+        }, { busyTimeoutMs: TELEMETRY_BUSY_TIMEOUT_MS });
+    }
+    catch (error) {
+        rethrowIfTestIsolationError(error);
+    }
+}

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

@@ -75,12 +75,17 @@ export function countUsageEventsByType(db, eventType) {
 /**
  * Delete usage events older than the given number of days.
  */
-export function purgeOldUsageEvents(db, retentionDays) {
+export function purgeOldUsageEvents(db, retentionDays, options) {
     if (!Number.isFinite(retentionDays) || retentionDays <= 0)
         return;
     try {
+        const stateSchema = options?.stateSchema;
+        if (stateSchema !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(stateSchema)) {
+            throw new Error("Invalid attached state schema name.");
+        }
+        const usageEvents = stateSchema === undefined ? "usage_events" : `"${stateSchema}".usage_events`;
         const cutoff = new Date(Date.now() - retentionDays * 86_400_000).toISOString();
-        db.prepare("DELETE FROM usage_events WHERE created_at < ?").run(cutoff);
+        db.prepare(`DELETE FROM ${usageEvents} WHERE created_at < ?`).run(cutoff);
     }
     catch {
         /* Table may not exist yet */

package/dist/indexer/walk/matchers.js

@@ -49,7 +49,7 @@ const DIR_TYPE_MAP = [
     {
         dir: "workflows",
         type: "workflow",
-        test: (ext) => ext === ".md",
+        test: (ext) => ext === ".md" || ext === ".yml",
     },
     {
         dir: "memories",
@@ -102,6 +102,13 @@ const DIR_TYPE_MAP = [
     },
 ];
 const COMMAND_PLACEHOLDER_RE = /\$ARGUMENTS|\$[123]\b/;
+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 },
+};
 // Files that should never be treated as the typed asset for the surrounding
 // directory (e.g. `workflows/README.md` is documentation, not a workflow).
 // Lower-cased and matched case-insensitively against `ctx.fileName`. They are
@@ -175,7 +182,7 @@ function classifyBySmartMd(ctx) {
     // body shape would otherwise classify (e.g. step-list inside a project
     // README under workflows/). Fall straight through to `knowledge`.
     if (isTypedDirDocFile(ctx.fileName)) {
-        return { type: "knowledge", specificity: 5 };
+        return SMART_MD_FACTS.knowledge;
     }
     const body = ctx.content();
     const fm = ctx.frontmatter();
@@ -185,33 +192,34 @@ function classifyBySmartMd(ctx) {
     // this only catches a workflow living OUTSIDE `workflows/` that still
     // declares its type explicitly.
     if (fm && fm.type === "workflow") {
-        return { type: "workflow", specificity: 19 };
+        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 { type: "agent", specificity: 20 };
+            return SMART_MD_FACTS.toolsAgent;
         }
         if ("agent" in fm) {
-            return { type: "command", specificity: 18 };
+            return SMART_MD_FACTS.command;
         }
     }
     if (COMMAND_PLACEHOLDER_RE.test(body)) {
-        return { type: "command", specificity: 18 };
+        return SMART_MD_FACTS.command;
     }
     if (fm && "model" in fm) {
-        return { type: "agent", specificity: 8 };
+        return SMART_MD_FACTS.modelAgent;
     }
-    return { type: "knowledge", specificity: 5 };
+    return SMART_MD_FACTS.knowledge;
 }
 // ---------------------------------------------------------------------------
 // Adapter: MatchFact → MatchResult
 // ---------------------------------------------------------------------------
 function toMatchResult(ctx, classify) {
     const fact = classify(ctx);
-    if (!fact)
-        return null;
+    return fact ? matchResultForFact(fact) : null;
+}
+function matchResultForFact(fact) {
     // Renderer name resolved via TYPE_PRESENTATION (core leaf), so matchers.ts
     // carries no edge into the taxonomy SCC (chunk-3 cutover enabler).
     // TYPE_PRESENTATION.renderer is the single source of truth for renderer names.
@@ -225,6 +233,28 @@ function toMatchResult(ctx, classify) {
         ...(fact.meta ? { meta: fact.meta } : {}),
     };
 }
+/**
+ * Every smart-Markdown result possible from path fields alone. The actual
+ * classifier above returns only facts from this shared table, so owner
+ * discovery can conservatively model a byte request without reading bytes.
+ */
+export function smartMdPathCandidates(ctx) {
+    if (ctx.ext !== ".md" || ctx.ancestorDirs.includes("secrets"))
+        return [];
+    const facts = isTypedDirDocFile(ctx.fileName)
+        ? [SMART_MD_FACTS.knowledge]
+        : [
+            SMART_MD_FACTS.workflow,
+            SMART_MD_FACTS.toolsAgent,
+            SMART_MD_FACTS.command,
+            SMART_MD_FACTS.modelAgent,
+            SMART_MD_FACTS.knowledge,
+        ];
+    return facts.flatMap((fact) => {
+        const result = matchResultForFact(fact);
+        return result ? [result] : [];
+    });
+}
 // ---------------------------------------------------------------------------
 // Public matchers (API unchanged)
 // ---------------------------------------------------------------------------

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

@@ -8,6 +8,7 @@ import { parseRefInput } from "../../core/asset/resolve-ref.js";
 import { isWithin } from "../../core/common.js";
 import { resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
 import { lookup } from "../indexer.js";
+import { deriveInstallations } from "../installations.js";
 import { resolveSourceEntries } from "../search/search-source.js";
 function normalizeRef(ref) {
     // String inputs use the current `[bundle//]conceptId` grammar.
@@ -65,8 +66,10 @@ function resolveViaDisk(ref, options) {
     }
     const directoryIndexNames = options.directoryIndexNames ?? ["SKILL.md"];
     const preserveDirectNameFallback = options.preserveDirectNameFallback ?? true;
-    for (const source of sources) {
-        if (options.writableDirSet && !options.writableDirSet.has(path.resolve(source.path)))
+    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) {

package/dist/indexer/walk/walker.js

@@ -11,6 +11,7 @@
 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"]);
@@ -128,7 +129,8 @@ function walkStashGit(stashRoot, options) {
             // 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.
-            if (fs.lstatSync(absPath).isFile()) {
+            const stat = fs.lstatSync(absPath);
+            if (stat.isFile() || (stat.isSymbolicLink() && isOwnedWorkflowSymlink(stashRoot, absPath, options))) {
                 results.push(buildFileContext(stashRoot, absPath));
             }
         }
@@ -219,7 +221,11 @@ function walkStashManual(stashRoot, options) {
                 continue;
             const fullPath = path.join(current, entry.name);
             if (entry.isSymbolicLink()) {
-                // Skip symlinks entirely to prevent potential path traversal outside stashRoot
+                // Native workflow components arbitrate file symlinks explicitly in the
+                // drain before reading them. Directory symlinks remain unfollowed.
+                if (isOwnedWorkflowSymlink(stashRoot, fullPath, options)) {
+                    results.push(buildFileContext(stashRoot, fullPath));
+                }
                 continue;
             }
             if (entry.isDirectory()) {
@@ -235,3 +241,15 @@ 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/"))
+        return false;
+    const extension = path.posix.extname(relativePath).toLowerCase();
+    return WORKFLOW_EXTENSIONS.includes(extension);
+}

package/dist/integrations/agent/builder-shared.js

@@ -14,12 +14,9 @@
  * their previous home in `builders.ts`.
  */
 import { UsageError } from "../../core/errors.js";
-import { resolveModel } from "./model-aliases.js";
-/** Resolve a raw dispatch model once, while preserving frozen/lowered models verbatim. */
-export function resolveDispatchModel(request, profile, platform) {
-    if (!request.model || request.modelIsExact)
-        return request.model;
-    return resolveModel(request.model, platform, profile.modelAliases, profile.globalModelAliases);
+/** Models reaching a harness have already crossed the single model-map boundary. */
+export function resolveDispatchModel(request, _profile, _platform) {
+    return request.model;
 }
 /**
  * Guard against values that start with `--`, which would be mis-interpreted as

package/dist/integrations/agent/conversation-fallback.js

@@ -0,0 +1,16 @@
+// 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 const CONVERSATION_FALLBACK_BEGIN = "<AKM_CONVERSATION_JSON>";
+export const CONVERSATION_FALLBACK_END = "</AKM_CONVERSATION_JSON>";
+/**
+ * Preserve ordered message roles for a one-shot transport with no native
+ * conversation channel. The fixed `{role,content}` projection and UTF-8 byte
+ * length make the embedded JSON unambiguous even when content contains marker
+ * text. The terminal command remains outside the prefix block.
+ */
+export function composeConversationFallbackPrompt(conversation, command) {
+    const json = JSON.stringify(conversation.map((message) => ({ role: message.role, content: message.content })));
+    const byteLength = new TextEncoder().encode(json).byteLength;
+    return `${CONVERSATION_FALLBACK_BEGIN} ${byteLength}\n${json}\n${CONVERSATION_FALLBACK_END}\n\n${command}`;
+}