akm-cli 0.7.4 → 0.7.5

package/dist/commands/distill.js

@@ -152,7 +152,12 @@ export async function akmDistill(options) {
     catch {
         assetContent = null;
     }
-    const { events } = readEventsImpl({ ref: inputRef, type: "feedback" });
+    const { events } = readEventsImpl({
+        ref: inputRef,
+        type: "feedback",
+        excludeTags: options.excludeTags,
+        includeTags: options.includeTags,
+    });
     // #267 — feedback exclusion. Filter events whose `ref` matches the
     // exclusion list BEFORE the prompt is built. The original event stream
     // is never mutated; only the `feedback` slice that reaches the LLM is
@@ -274,10 +279,15 @@ async function defaultLookup(ref) {
 }
 /** Best-effort fence stripping. Keeps the body intact when no fence is present. */
 function stripMarkdownFences(raw) {
-    const trimmed = raw.trim();
+    // Strip <think>…</think> reasoning blocks first — local LLMs (e.g. Qwen3)
+    // emit these before the content, which breaks YAML frontmatter detection.
+    const stripped = raw
+        .trim()
+        .replace(/<think>[\s\S]*?<\/think>/gi, "")
+        .trim();
     // Only strip outer triple-fence pairs — leave inner code blocks alone.
-    const fence = trimmed.match(/^```(?:markdown|md)?\s*\n([\s\S]*?)\n```\s*$/i);
+    const fence = stripped.match(/^```(?:markdown|md)?\s*\n([\s\S]*?)\n```\s*$/i);
     if (fence)
         return fence[1].trim();
-    return trimmed;
+    return stripped;
 }

package/dist/commands/events.js

@@ -67,7 +67,14 @@ function normalizeSince(since) {
 export function akmEventsList(options = {}) {
     const ref = validateRef(options.ref);
     const parsed = parseSinceFlag(options.since);
-    const result = readEvents({ since: parsed.since, sinceOffset: parsed.sinceOffset, type: options.type, ref }, options.ctx);
+    const result = readEvents({
+        since: parsed.since,
+        sinceOffset: parsed.sinceOffset,
+        type: options.type,
+        ref,
+        excludeTags: options.excludeTags,
+        includeTags: options.includeTags,
+    }, options.ctx);
     return {
         schemaVersion: 1,
         totalCount: result.events.length,
@@ -92,6 +99,8 @@ export async function akmEventsTail(options = {}) {
         maxEvents: options.maxEvents,
         signal: options.signal,
         onEvent: options.onEvent,
+        excludeTags: options.excludeTags,
+        includeTags: options.includeTags,
     };
     const result = await tailEvents(tailOptions, options.ctx);
     return {

package/dist/commands/migration-help.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-const CHANGELOG_URL = "https://github.com/itlackey/akm/blob/main/CHANGELOG.md";
+const CHANGELOG_URL = "https://github.com/itlackey/akm/blob/main/.github/CHANGELOG.md";
 const MIGRATION_DOC_URL = "https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md";
 /**
  * Directory containing per-version release notes. Resolved relative to
@@ -14,7 +14,7 @@ function releaseNotesDir() {
 }
 function loadChangelog() {
     try {
-        const changelogPath = path.resolve(import.meta.dir, "../../CHANGELOG.md");
+        const changelogPath = path.resolve(import.meta.dir, "../../.github/CHANGELOG.md");
         if (fs.existsSync(changelogPath)) {
             return fs.readFileSync(changelogPath, "utf8");
         }

package/dist/commands/propose.js

@@ -78,14 +78,21 @@ export async function akmPropose(options) {
         throw err;
     }
     // 3. Build prompt.
+    // Synthesize a temp draft path so opencode can write the asset content
+    // directly using its file tools rather than returning JSON via stdout.
+    const draftFilePath = import("node:os").then((os) => import("node:path").then((path) => path.join(os.tmpdir(), `akm-propose-${options.type}-${options.name.replace(/[^a-z0-9_-]/gi, "_")}-${Date.now()}.md`)));
+    const resolvedDraftPath = await draftFilePath;
     const prompt = buildProposePrompt({
         type: options.type,
         name: options.name,
         task: options.task,
+        draftFilePath: resolvedDraftPath,
     });
     // 4. Spawn the agent.
+    // Real agent runs use interactive mode so file tools can write the draft.
+    // Injected/custom spawns still need captured stdout for JSON payload tests.
     const runOptions = {
-        stdio: "captured",
+        stdio: options.runAgentOptions?.spawn ? "captured" : "interactive",
         parseOutput: "text",
         ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
         ...(options.runAgentOptions ?? {}),
@@ -94,24 +101,37 @@ export async function akmPropose(options) {
     if (!result.ok) {
         return failureEnvelope(result, options.type, options.name);
     }
-    // 5. Parse the structured response.
+    // 5. Resolve the proposal content.
+    // Path A: opencode wrote the draft file — read it directly (no stdout parse).
+    // Path B: fallback to stdout JSON parse for non-file-writing agents.
+    const fs = await import("node:fs");
     let payload;
-    try {
-        payload = parseAgentProposalPayload(result.stdout);
-    }
-    catch (err) {
-        return {
-            schemaVersion: 1,
-            ok: false,
-            reason: "parse_error",
-            error: err instanceof Error ? err.message : String(err),
-            type: options.type,
-            name: options.name,
-            exitCode: result.exitCode,
-            stdout: result.stdout,
-            ...(result.stderr ? { stderr: result.stderr } : {}),
+    if (fs.existsSync(resolvedDraftPath)) {
+        const draftContent = fs.readFileSync(resolvedDraftPath, "utf8");
+        fs.unlinkSync(resolvedDraftPath);
+        payload = {
+            ref: `${options.type}:${options.name}`,
+            content: draftContent,
         };
     }
+    else {
+        try {
+            payload = parseAgentProposalPayload(result.stdout ?? "");
+        }
+        catch (err) {
+            return {
+                schemaVersion: 1,
+                ok: false,
+                reason: "parse_error",
+                error: err instanceof Error ? err.message : String(err),
+                type: options.type,
+                name: options.name,
+                exitCode: result.exitCode,
+                stdout: result.stdout,
+                ...(result.stderr ? { stderr: result.stderr } : {}),
+            };
+        }
+    }
     // 6. Insert the proposal. Note: we allow the agent's `ref` to normalise the
     // asset name (e.g. path-cleanup), but only after validating that the ref is
     // well-formed and the type still matches the requested type.

package/dist/commands/reflect.js

@@ -68,6 +68,24 @@ function buildSchemaHints(type, content) {
     const report = lintLessonContent(content, "reflect");
     return report.findings.map((f) => `[${f.kind}] ${f.message}`);
 }
+function fallbackPayloadFromRawContent(stdout, ref) {
+    if (!ref)
+        return undefined;
+    const trimmed = stripMarkdownFence(stdout).trim();
+    if (!trimmed)
+        return undefined;
+    if (!looksLikeAssetContent(trimmed))
+        return undefined;
+    return { ref, content: trimmed };
+}
+function stripMarkdownFence(stdout) {
+    const trimmed = stdout.trim();
+    const match = trimmed.match(/^```(?:markdown|md)?\s*\n([\s\S]*?)\n```$/i);
+    return match?.[1] ?? trimmed;
+}
+function looksLikeAssetContent(value) {
+    return value.startsWith("#") || value.startsWith("---");
+}
 function loadAgentConfigFromDisk() {
     const config = loadConfig();
     return parseAgentConfig(config.agent);
@@ -130,6 +148,9 @@ export async function akmReflect(options = {}) {
         throw err;
     }
     // 4. Build the prompt.
+    // Keep reflect on the same captured JSON path the bench harness already
+    // uses successfully. The draft-file interactive path proved brittle with
+    // local opencode models and caused proposal generation failures.
     const feedback = readRecentFeedback(options.ref);
     const schemaHints = buildSchemaHints(parsedRef?.type ?? "", assetContent);
     const prompt = buildReflectPrompt({
@@ -141,8 +162,7 @@ export async function akmReflect(options = {}) {
         ...(schemaHints.length > 0 ? { schemaHints } : {}),
         ...(options.task ? { task: options.task } : {}),
     });
-    // 5. Spawn the agent. Force captured stdio + JSON parse so we can extract
-    // the structured payload without confusing terminal control codes.
+    // 5. Spawn the agent.
     const runOptions = {
         stdio: "captured",
         parseOutput: "text",
@@ -153,22 +173,28 @@ export async function akmReflect(options = {}) {
     if (!result.ok) {
         return failureEnvelope(result, options.ref);
     }
-    // 6. Parse stdout into a proposal payload.
+    // 6. Resolve the proposal content from stdout JSON.
     let payload;
     try {
-        payload = parseAgentProposalPayload(result.stdout);
+        payload = parseAgentProposalPayload(result.stdout ?? "");
     }
     catch (err) {
-        return {
-            schemaVersion: 1,
-            ok: false,
-            reason: "parse_error",
-            error: err instanceof Error ? err.message : String(err),
-            ...(options.ref ? { ref: options.ref } : {}),
-            exitCode: result.exitCode,
-            stdout: result.stdout,
-            ...(result.stderr ? { stderr: result.stderr } : {}),
-        };
+        const fallback = fallbackPayloadFromRawContent(result.stdout ?? "", options.ref);
+        if (fallback) {
+            payload = fallback;
+        }
+        else {
+            return {
+                schemaVersion: 1,
+                ok: false,
+                reason: "parse_error",
+                error: err instanceof Error ? err.message : String(err),
+                ...(options.ref ? { ref: options.ref } : {}),
+                exitCode: result.exitCode,
+                stdout: result.stdout,
+                ...(result.stderr ? { stderr: result.stderr } : {}),
+            };
+        }
     }
     // 7. Create the proposal. The proposal queue is the ONLY thing reflect
     // writes — promotion to a real asset is gated by `akm proposal accept`.

package/dist/commands/remember.js

@@ -138,7 +138,7 @@ export async function runLlmEnrich(body) {
         return { tags: [] };
     }
     const llmConfig = config.llm;
-    const { chatCompletion, parseJsonResponse } = await import("../llm/client");
+    const { chatCompletion, parseEmbeddedJsonResponse: parseJsonResponse } = await import("../llm/client");
     const prompt = `You are a memory tagger for a developer knowledge base.
 Given the memory text below, return ONLY a JSON object with these fields:
 - "tags": array of 1-5 short lowercase keyword tags

package/dist/commands/show.js

@@ -9,15 +9,9 @@
  * edit-hints, summary-detail truncation) lives below in this file. The flow:
  *
  *   1. Special-case wiki-root refs (`wiki:<name>` with no page path).
- *   2. Ask `indexer.lookup(ref)` for the row in the FTS index.
- *   3. Fall back to the on-disk type-dir resolver only when the index has
- *      no matching row — covers the "indexed yet?" gap when the user has
- *      just added a file and not run `akm index`.
+ *   2. Auto-index when stale so the index is current.
+ *   3. Ask `indexer.lookup(ref)` for the row in the FTS index.
  *   4. Render the file via the matcher/renderer pipeline.
- *
- * Step (2) is the v1 spec change: reading is the indexer's job. Step (3) is a
- * pragmatic safety net (NOT remote provider fallback, which the spec
- * forbids — "Show: Local FTS5 index only. No remote provider fallback.").
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -27,6 +21,7 @@ import { NotFoundError, UsageError } from "../core/errors";
 import { appendEvent, readEvents } from "../core/events";
 import { parseFrontmatter, toStringOrUndefined } from "../core/frontmatter";
 import { closeDatabase, findEntryIdByRef, openExistingDatabase } from "../indexer/db";
+import { ensureIndex } from "../indexer/ensure-index";
 import { buildFileContext, buildRenderContext, getRenderer, runMatchers } from "../indexer/file-context";
 import { lookup } from "../indexer/indexer";
 import { buildEditHint, findSourceForPath, isEditable, resolveSourceEntries } from "../indexer/search-source";
@@ -34,8 +29,8 @@ import { insertUsageEvent } from "../indexer/usage-events";
 import { resolveSourcesForOrigin } from "../registry/origin-resolve";
 // Eagerly import source providers to trigger self-registration.
 import "../sources/providers/index";
-import { resolveAssetPath } from "../sources/resolve";
 import { getActiveWorkflowRun } from "../workflows/runs";
+import { getCurrentWorkflowScopeKey } from "../workflows/scope-key";
 /**
  * Show a wiki root (no page path) — returns the same payload as
  * `akm wiki show <name>`.
@@ -128,7 +123,12 @@ export async function akmShowUnified(input) {
                 new NotFoundError(`Wiki not found: ${parsed.name}. Run \`akm wiki create ${parsed.name}\` to create it.`));
         }
     }
-    // Try local filesystem (FTS5 index lookup, then on-disk fallback)
+    // Auto-index when stale so the index is current before lookup.
+    const allSources = resolveSourceEntries();
+    if (allSources.length > 0) {
+        await ensureIndex(allSources[0].path);
+    }
+    // Try local filesystem (FTS5 index lookup)
     const result = await showLocal(input);
     // Scope filter narrows resolution: if --scope was supplied, the asset's
     // frontmatter scope must satisfy every supplied key. We re-read the file
@@ -220,38 +220,16 @@ function logShowEvent(ref, existingDb) {
     }
 }
 /**
- * Resolve an asset path to a file via:
- *   1. `indexer.lookup(ref)` — the spec's primary path (§6.2).
- *   2. On-disk type-dir traversal — fallback for files not yet indexed.
+ * Resolve an asset path via the FTS5 index only. Spec §6.2's primary path.
  *
- * Returns `undefined` if neither path finds a match.
+ * Returns `undefined` if the index has no matching row.
  */
-async function resolvePathViaIndexThenDisk(parsed, searchSourceDirs) {
-    // Step 1: indexer
-    try {
-        const entry = await lookup(parsed);
-        if (entry) {
-            return { assetPath: entry.filePath };
-        }
-    }
-    catch (err) {
-        // Index unavailable (e.g. DB doesn't exist yet) — fall back to disk walk.
-        if (!(err instanceof NotFoundError)) {
-            // continue to disk fallback
-        }
-    }
-    // Step 2: on-disk type-dir traversal
-    let lastError;
-    for (const dir of searchSourceDirs) {
-        try {
-            const assetPath = await resolveAssetPath(dir, parsed.type, parsed.name);
-            return { assetPath, lastError };
-        }
-        catch (err) {
-            lastError = err instanceof Error ? err : new Error(String(err));
-        }
+async function resolvePathViaIndex(parsed) {
+    const entry = await lookup(parsed);
+    if (entry) {
+        return { assetPath: entry.filePath };
     }
-    return lastError ? { assetPath: "", lastError } : undefined;
+    return undefined;
 }
 /** @internal Use akmShowUnified() for all external callers. */
 export async function showLocal(input) {
@@ -273,13 +251,10 @@ export async function showLocal(input) {
         }
     }
     if (!assetPath) {
-        const resolved = await resolvePathViaIndexThenDisk(parsed, allSourceDirs);
+        const resolved = await resolvePathViaIndex(parsed);
         if (resolved?.assetPath) {
             assetPath = resolved.assetPath;
         }
-        else if (resolved?.lastError) {
-            lastError = resolved.lastError;
-        }
     }
     if (!assetPath && parsed.origin && searchSources.length === 0) {
         const installCmd = `akm add ${parsed.origin}`;
@@ -319,7 +294,7 @@ export async function showLocal(input) {
         editable,
         ...(!editable ? { editHint: buildEditHint(assetPath, parsed.type, parsed.name, source?.registryId) } : {}),
     };
-    const activeRun = getActiveWorkflowRun();
+    const activeRun = getActiveWorkflowRun(getCurrentWorkflowScopeKey());
     if (activeRun) {
         fullResponse.activeRun = activeRun;
     }

package/dist/commands/vault.js

@@ -5,13 +5,9 @@
  * the indexer, the `akm show` renderer, or any structured output channel.
  * The supported load paths are:
  *
- *   - `eval "$(akm vault load vault:<name>)"` — `vault load` parses the vault
- *     with dotenv (no shell expansion, no code execution), writes a safely
- *     single-quote-escaped `export KEY='value'` script to a mode-0600 temp
- *     file, and emits `. <tmp>; rm -f <tmp>` on stdout. Values reach bash
- *     only via the temp file, never via akm's stdout.
- *   - `injectIntoEnv(vaultPath, target)` — programmatic API for modules that
- *     need values in a process environment.
+ *   - `source "$(akm vault path vault:<name>)"` — direct shell loading path.
+ *   - `injectIntoEnv(vaultPath, target)` / `loadEnv(vaultPath)` — programmatic
+ *     APIs for modules that need values in process memory.
  *
  * Value parsing is delegated to the `dotenv` package — we deliberately do not
  * implement our own quoting/escaping rules for security-sensitive content.
@@ -144,8 +140,7 @@ export function injectIntoEnv(vaultPath, target = process.env) {
  * non-assignment content, so sourcing the output is safe regardless of what
  * the vault file contains.
  *
- * Intended for use by `akm vault load`, which writes this to a mode-0600
- * temp file and emits only the path (never values) on stdout.
+ * Retained for programmatic callers/tests that need a literal export script.
  */
 export function buildShellExportScript(vaultPath) {
     const env = loadEnv(vaultPath);
@@ -264,7 +259,7 @@ export function createVault(vaultPath) {
  * Characters that are safe in an UNquoted dotenv value AND are not
  * metacharacters in POSIX shells. Anything outside this set forces quoting,
  * which is defense-in-depth for any caller that might ever `source` the
- * vault file directly instead of going through `akm vault load`.
+ * vault file directly instead of going through `akm vault path`.
  */
 const UNQUOTED_SAFE_RE = /^[A-Za-z0-9_.:/@%+,-]+$/;
 /**

package/dist/core/asset-registry.js

@@ -32,7 +32,7 @@ export const ACTION_BUILDERS = {
     knowledge: (ref) => `akm show ${ref} -> read reference material`,
     memory: (ref) => `akm show ${ref} -> recall context`,
     workflow: (ref) => buildWorkflowAction(ref),
-    vault: (ref) => `akm vault list ${ref} -> see key names; eval "$(akm vault load ${ref})" -> load values into the current shell (values never echoed)`,
+    vault: (ref) => `akm show ${ref} -> inspect keys; source "$(akm vault path ${ref})" -> load values; akm vault run ${ref} -- <command> -> run with injected env`,
     wiki: (ref) => `akm show ${ref} -> read the wiki page`,
 };
 /**

package/dist/core/asset-spec.js

@@ -82,7 +82,7 @@ const ASSET_SPECS_INTERNAL = {
             return path.join(typeRoot, name.endsWith(".env") ? name : `${name}.env`);
         },
         rendererName: "vault-env",
-        actionBuilder: (ref) => `akm vault list ${ref} -> see key names; eval "$(akm vault load ${ref})" -> load values into the current shell (values never echoed)`,
+        actionBuilder: (ref) => `akm show ${ref} -> inspect keys; source "$(akm vault path ${ref})" -> load values; akm vault run ${ref} -- <command> -> run with injected env`,
     },
     wiki: {
         stashDir: "wikis",

package/dist/core/config.js

@@ -485,6 +485,10 @@ function parseLlmConfig(value) {
         warn(`[akm] Ignoring llm config: endpoint must start with http:// or https://, got "${obj.endpoint}"`);
         return undefined;
     }
+    if (!obj.endpoint.endsWith("/chat/completions")) {
+        warn(`[akm] llm.endpoint "${obj.endpoint}" does not end in /chat/completions. ` +
+            `Did you mean "${obj.endpoint.replace(/\/+$/, "")}/chat/completions"?`);
+    }
     const model = typeof obj.model === "string" ? obj.model : "";
     const result = {
         endpoint: obj.endpoint,
@@ -496,6 +500,15 @@ function parseLlmConfig(value) {
     if (typeof obj.temperature === "number" && Number.isFinite(obj.temperature)) {
         result.temperature = obj.temperature;
     }
+    if ("timeoutMs" in obj) {
+        if (typeof obj.timeoutMs !== "number" ||
+            !Number.isFinite(obj.timeoutMs) ||
+            !Number.isInteger(obj.timeoutMs) ||
+            obj.timeoutMs <= 0) {
+            return undefined;
+        }
+        result.timeoutMs = obj.timeoutMs;
+    }
     if ("maxTokens" in obj) {
         if (typeof obj.maxTokens !== "number" ||
             !Number.isFinite(obj.maxTokens) ||

package/dist/core/events.js

@@ -158,6 +158,11 @@ function matchesFilter(envelope, options) {
         return false;
     if (options.since && envelope.ts && envelope.ts < options.since)
         return false;
+    const tags = envelope.metadata?.tags ?? [];
+    if (options.excludeTags?.some((t) => tags.includes(t)))
+        return false;
+    if (options.includeTags && !options.includeTags.every((t) => tags.includes(t)))
+        return false;
     return true;
 }
 /**
@@ -178,7 +183,13 @@ export async function tailEvents(options = {}, ctx) {
     // we start polling. This matches the documented behaviour of `tail
     // --since`: emit existing events that match, then follow.
     if (options.sinceOffset === undefined) {
-        const initial = readEvents({ since: options.since, type: options.type, ref: options.ref }, ctx);
+        const initial = readEvents({
+            since: options.since,
+            type: options.type,
+            ref: options.ref,
+            excludeTags: options.excludeTags,
+            includeTags: options.includeTags,
+        }, ctx);
         for (const event of initial.events) {
             collected.push(event);
             options.onEvent?.(event);
@@ -202,7 +213,13 @@ export async function tailEvents(options = {}, ctx) {
         }
         function tick() {
             try {
-                const result = readEvents({ sinceOffset: cursor, type: options.type, ref: options.ref }, ctx);
+                const result = readEvents({
+                    sinceOffset: cursor,
+                    type: options.type,
+                    ref: options.ref,
+                    excludeTags: options.excludeTags,
+                    includeTags: options.includeTags,
+                }, ctx);
                 cursor = result.nextOffset;
                 for (const event of result.events) {
                     // Apply --since filter inside the polling loop too — the cursor is