akm-cli 0.7.0-rc1 → 0.7.0

package/dist/src/commands/source-add.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { isHttpUrl, resolveStashDir } from "../core/common";
 import { loadConfig, loadUserConfig, saveConfig } from "../core/config";
-import { UsageError } from "../core/errors";
+import { ConfigError, UsageError } from "../core/errors";
 import { warn } from "../core/warn";
 import { akmIndex } from "../indexer/indexer";
 import { upsertLockEntry } from "../integrations/lockfile";
@@ -190,6 +190,10 @@ async function addWebsiteSource(ref, stashDir, name, options, wikiName) {
  * persisting the lock entry.
  */
 async function addRegistryStash(ref, stashDir, trustThisInstall, writable, wikiName) {
+    const parsedRef = parseRegistryRef(ref);
+    if (writable === true && parsedRef.source !== "git") {
+        throw new ConfigError("writable: true is only supported on filesystem and git sources", "INVALID_CONFIG_FILE");
+    }
     // Pre-sync registry-policy enforcement uses just the parsed ref (no fetch needed),
     // so we keep parity with the historical behavior where `enforceRegistryInstallPolicy`
     // ran before `extractTarGzSecure` etc.

package/dist/src/commands/source-manage.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { loadConfig, loadUserConfig, saveConfig } from "../core/config";
-import { UsageError } from "../core/errors";
+import { ConfigError, UsageError } from "../core/errors";
 import { resolveSourceEntries } from "../indexer/search-source";
 // ── Operations ──────────────────────────────────────────────────────────────
 /**
@@ -12,6 +12,12 @@ import { resolveSourceEntries } from "../indexer/search-source";
  */
 export function addStash(opts) {
     const { target, name, providerType, options: providerOptions, writable } = opts;
+    if (providerType === "openviking") {
+        throw new ConfigError("openviking is not supported in akm v1.", "INVALID_CONFIG_FILE");
+    }
+    if (writable === true && providerType && providerType !== "filesystem" && providerType !== "git") {
+        throw new ConfigError("writable: true is only supported on filesystem and git sources", "INVALID_CONFIG_FILE");
+    }
     const config = loadUserConfig();
     const sources = [...(config.sources ?? config.stashes ?? [])];
     const isRemoteUrl = target.startsWith("http://") ||

package/dist/src/core/config.js

@@ -169,6 +169,9 @@ export function updateConfig(partial) {
  */
 function pickKnownKeys(raw) {
     const config = {};
+    if (Array.isArray(raw.stashes)) {
+        throw new ConfigError("The legacy `stashes[]` config key is no longer supported; rename it to `sources[]`.", "INVALID_CONFIG_FILE", `Edit ${_getConfigPath()} and replace \`stashes\` with \`sources\`.`);
+    }
     if (typeof raw.stashDir === "string" && raw.stashDir.trim()) {
         config.stashDir = raw.stashDir.trim();
     }
@@ -436,6 +439,28 @@ function parseEmbeddingConfig(value) {
     if (localModel) {
         result.localModel = localModel;
     }
+    if ("contextLength" in obj) {
+        if (typeof obj.contextLength !== "number" ||
+            !Number.isFinite(obj.contextLength) ||
+            !Number.isInteger(obj.contextLength) ||
+            obj.contextLength <= 0) {
+            return undefined;
+        }
+        result.contextLength = obj.contextLength;
+    }
+    if (typeof obj.ollamaOptions === "object" && obj.ollamaOptions !== null && !Array.isArray(obj.ollamaOptions)) {
+        const opts = obj.ollamaOptions;
+        const parsed = {};
+        if (typeof opts.num_ctx === "number" &&
+            Number.isFinite(opts.num_ctx) &&
+            Number.isInteger(opts.num_ctx) &&
+            opts.num_ctx > 0) {
+            parsed.num_ctx = opts.num_ctx;
+        }
+        if (Object.keys(parsed).length > 0) {
+            result.ollamaOptions = parsed;
+        }
+    }
     return result;
 }
 function parseLlmConfig(value) {
@@ -619,6 +644,9 @@ function parseInstalledStashEntry(value) {
     };
     if (typeof obj.writable === "boolean")
         entry.writable = obj.writable;
+    if (entry.writable === true && entry.source !== "git") {
+        throw new ConfigError(`writable: true is only supported on filesystem and git sources (got "${entry.source}" on installed entry "${entry.id}").`, "INVALID_CONFIG_FILE", "Remove `writable: true` from the installed entry or re-add it as a git source instead.");
+    }
     const resolvedVersion = asNonEmptyString(obj.resolvedVersion);
     if (resolvedVersion)
         entry.resolvedVersion = resolvedVersion;

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

@@ -294,6 +294,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
         const TYPE_BOOST = {
             skill: 0.4,
             command: 0.35,
+            workflow: 0.35,
             agent: 0.3,
             script: 0.2,
             memory: 0.1,

package/dist/src/indexer/indexer.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { isHttpUrl, resolveStashDir, toErrorMessage } from "../core/common";
 import { getDbPath } from "../core/paths";
-import { isVerbose, warn } from "../core/warn";
+import { isVerbose, warn, warnVerbose } from "../core/warn";
 import { resolveIndexPassLLM } from "../llm/index-passes";
 import { takeWorkflowDocument } from "../workflows/document-cache";
 import { closeDatabase, deleteEntriesByDir, deleteEntriesByStashDir, getEmbeddingCount, getEntriesByDir, getEntryCount, getMeta, isVecAvailable, openDatabase, rebuildFts, setMeta, upsertEmbedding, upsertEntry, upsertUtilityScore, warnIfVecMissing, } from "./db";
@@ -503,6 +503,7 @@ async function generateEmbeddingsForDb(db, config, onProgress) {
     }
     try {
         const { embedBatch } = await import("../llm/embedder.js");
+        const { estimateTokenCount } = await import("../llm/embedders/remote.js");
         const allEntries = getAllEntriesForEmbedding(db);
         if (allEntries.length === 0) {
             onProgress({ phase: "embeddings", message: "Embeddings already up to date." });
@@ -514,6 +515,19 @@ async function generateEmbeddingsForDb(db, config, onProgress) {
             message: `Generating embeddings for ${allEntries.length} entr${allEntries.length === 1 ? "y" : "ies"}.`,
         });
         const texts = allEntries.map((e) => e.searchText);
+        // Verbose: log each document before it is sent to the embedding API so
+        // operators can see exactly where embedding fails without waiting for an error.
+        if (isVerbose()) {
+            const EMBED_BATCH_SIZE = 100; // mirrors REMOTE_BATCH_SIZE in remote.ts
+            const totalBatches = Math.ceil(texts.length / EMBED_BATCH_SIZE);
+            for (let i = 0; i < texts.length; i++) {
+                const batchNum = Math.floor(i / EMBED_BATCH_SIZE) + 1;
+                const chars = texts[i].length;
+                const tokens = estimateTokenCount(texts[i]);
+                const ref = allEntries[i].entryKey.split(":").slice(1).join(":"); // strip stashDir prefix
+                warnVerbose(`[embed] ${ref} (${chars} chars, est. ${tokens} tokens) → batch ${batchNum}/${totalBatches}`);
+            }
+        }
         const embeddings = await embedBatch(texts, config.embedding);
         // Wrap all embedding upserts in a single transaction so partial
         // state is rolled back on failure rather than leaving the table half-filled.
@@ -547,7 +561,7 @@ async function generateEmbeddingsForDb(db, config, onProgress) {
 function getAllEntriesForEmbedding(db) {
     return db
         .prepare(`
-      SELECT e.id, e.search_text AS searchText FROM entries e
+      SELECT e.id, e.search_text AS searchText, e.entry_key AS entryKey, e.file_path AS filePath FROM entries e
       WHERE NOT EXISTS (SELECT 1 FROM embeddings b WHERE b.id = e.id)
     `)
         .all();

package/dist/src/indexer/matchers.js

@@ -97,7 +97,7 @@ export function parentDirHintMatcher(ctx) {
     if (parentDir === "scripts" && SCRIPT_EXTENSIONS.has(ext)) {
         return { type: "script", specificity: 15, renderer: "script-source" };
     }
-    if (parentDir === "skills" && fileName === "SKILL.md") {
+    if (parentDir === "skills" && (fileName === "SKILL.md" || ext === ".md")) {
         return { type: "skill", specificity: 15, renderer: "skill-md" };
     }
     if (parentDir === "agents" && ext === ".md") {

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

@@ -224,7 +224,9 @@ function isValidDirectory(dir) {
  */
 export async function ensureSourceCaches(config) {
     const cfg = config ?? loadConfig();
-    for (const entry of cfg.stashes ?? []) {
+    // Use sources[] (current key) with fallback to stashes[] (deprecated, one-release compat).
+    const entries = cfg.sources ?? cfg.stashes ?? [];
+    for (const entry of entries) {
         if (!GIT_STASH_TYPES.has(entry.type) || !entry.url || entry.enabled === false)
             continue;
         try {
@@ -236,7 +238,7 @@ export async function ensureSourceCaches(config) {
             warn(`Warning: failed to refresh git mirror for "${entry.url}": ${err instanceof Error ? err.message : String(err)}`);
         }
     }
-    for (const entry of cfg.stashes ?? []) {
+    for (const entry of entries) {
         if (entry.type !== "website" || !entry.url || entry.enabled === false)
             continue;
         try {

package/dist/src/integrations/agent/profiles.js

@@ -8,7 +8,7 @@ const BUILTINS = {
     opencode: {
         name: "opencode",
         bin: "opencode",
-        args: [],
+        args: ["run"],
         stdio: "interactive",
         envPassthrough: [...COMMON_PASSTHROUGH, "OPENCODE_API_KEY", "OPENCODE_CONFIG"],
         parseOutput: "text",

package/dist/src/integrations/agent/spawn.js

@@ -12,6 +12,32 @@
  * this is a pre-emptive guarantee against the #222 invariant.
  */
 import { DEFAULT_AGENT_TIMEOUT_MS } from "./config";
+/**
+ * Kill the process group of `proc` with `signal`, falling back to
+ * `proc.kill(signal)` when `proc.pid` is unavailable (e.g. test fakes).
+ *
+ * Passing a negative PID to `process.kill` targets the entire process
+ * group, so opencode's child processes (the .opencode binary, etc.) are
+ * reaped alongside the node wrapper. The fallback keeps test fakes working
+ * without modification.
+ */
+export function killGroup(proc, signal) {
+    if (typeof proc.pid === "number") {
+        try {
+            process.kill(-proc.pid, signal);
+            return;
+        }
+        catch {
+            // Process may have already exited; fall through to direct kill.
+        }
+    }
+    try {
+        proc.kill(signal);
+    }
+    catch {
+        /* ignore */
+    }
+}
 const DEFAULT_TIMEOUT_MS = DEFAULT_AGENT_TIMEOUT_MS;
 function resolveSpawnFn(options) {
     if (options.spawn)
@@ -47,15 +73,21 @@ function buildChildEnv(profile, options) {
     }
     return env;
 }
-async function readStream(stream) {
+async function readStream(stream, opts) {
     if (!stream)
         return "";
-    try {
-        return await new Response(stream).text();
-    }
-    catch {
-        return "";
-    }
+    const readPromise = new Response(stream).text().catch(() => "");
+    if (!opts?.timeoutMs)
+        return readPromise;
+    // Race the stream read against a timeout so a process that is killed via
+    // SIGTERM/SIGKILL but whose pipe endpoints stay open (e.g. background
+    // threads still holding the fd) cannot block the caller indefinitely.
+    // On timeout we return whatever we received so far (empty string here since
+    // `readPromise` is all-or-nothing with `Response.text()`).
+    const timeoutPromise = new Promise((resolve) => {
+        setTimeout(() => resolve(""), opts.timeoutMs);
+    });
+    return Promise.race([readPromise, timeoutPromise]);
 }
 /**
  * Spawn the agent CLI described by `profile` with `prompt` (forwarded as
@@ -90,11 +122,16 @@ export async function runAgent(profile, prompt, options = {}) {
     try {
         const spawnFn = resolveSpawnFn(options);
         proc = spawnFn([profile.bin, ...args], {
-            stdin: stdioMode === "captured" ? "pipe" : "inherit",
+            stdin: stdioMode === "captured" ? (options.stdin !== undefined ? "pipe" : "ignore") : "inherit",
             stdout: stdioMode === "captured" ? "pipe" : "inherit",
             stderr: stdioMode === "captured" ? "pipe" : "inherit",
             env,
             ...(options.cwd ? { cwd: options.cwd } : {}),
+            // Spawn in its own process group so killGroup(-pid, signal) reaches all
+            // descendants (e.g. the .opencode binary that opencode's node wrapper forks).
+            // Only applied in captured mode — interactive mode inherits the parent
+            // terminal's process group intentionally.
+            ...(stdioMode === "captured" ? { detached: true } : {}),
         });
     }
     catch (err) {
@@ -121,15 +158,27 @@ export async function runAgent(profile, prompt, options = {}) {
         if (proc.exitCode !== null)
             return;
         timedOut = true;
-        try {
-            proc.kill("SIGTERM");
-        }
-        catch {
-            /* ignore */
-        }
+        killGroup(proc, "SIGTERM");
+        // Follow up with SIGKILL after 5 s in case the process ignores SIGTERM.
+        setTimeoutImpl(() => {
+            if (proc.exitCode !== null)
+                return;
+            killGroup(proc, "SIGKILL");
+        }, 5000);
     }, timeoutMs);
-    const stdoutPromise = stdioMode === "captured" ? readStream(proc.stdout ?? null) : Promise.resolve("");
-    const stderrPromise = stdioMode === "captured" ? readStream(proc.stderr ?? null) : Promise.resolve("");
+    // Stream-drain timeout: the overall wall-clock budget plus a 2 s grace
+    // period. When a process is killed via SIGTERM/SIGKILL (from our timeout
+    // handler or from outside) some runtimes keep the pipe write-end open in
+    // background threads, which would cause `Response.text()` to block forever.
+    // Capping stream draining at `timeoutMs + 2 000 ms` ensures the caller
+    // never hangs past the wall budget regardless of subprocess pipe behaviour.
+    const streamDrainTimeoutMs = timeoutMs + 2_000;
+    const stdoutPromise = stdioMode === "captured"
+        ? readStream(proc.stdout ?? null, { timeoutMs: streamDrainTimeoutMs })
+        : Promise.resolve("");
+    const stderrPromise = stdioMode === "captured"
+        ? readStream(proc.stderr ?? null, { timeoutMs: streamDrainTimeoutMs })
+        : Promise.resolve("");
     // Optional stdin payload (captured mode only).
     //
     // BUG-H1: race the stdin write/close against `proc.exited` and the
@@ -163,6 +212,8 @@ export async function runAgent(profile, prompt, options = {}) {
         clearTimeoutImpl(timer);
         // BUG-H2: drain stream readers before the early return so they don't
         // surface as unhandled rejections after the function resolves.
+        // The streams already carry a built-in drain timeout so this allSettled
+        // will not block indefinitely.
         await Promise.allSettled([stdoutPromise, stderrPromise]);
         const durationMs = Date.now() - start;
         return {

package/dist/src/integrations/github.js

@@ -2,8 +2,13 @@ import * as childProcess from "node:child_process";
 export const GITHUB_API_BASE = "https://api.github.com";
 const GITHUB_TOKEN_DOMAINS = new Set(["api.github.com", "github.com", "uploads.github.com"]);
 function readGithubTokenFromEnv() {
-    const token = process.env.GITHUB_TOKEN?.trim() || process.env.GH_TOKEN?.trim();
-    return token || undefined;
+    if (process.env.GITHUB_TOKEN !== undefined) {
+        return process.env.GITHUB_TOKEN.trim();
+    }
+    if (process.env.GH_TOKEN !== undefined) {
+        return process.env.GH_TOKEN.trim();
+    }
+    return undefined;
 }
 function readGithubTokenFromGhCli() {
     const result = childProcess.spawnSync("gh", ["auth", "token"], {
@@ -17,7 +22,8 @@ function readGithubTokenFromGhCli() {
     return token || undefined;
 }
 function resolveGithubToken() {
-    return readGithubTokenFromEnv() ?? readGithubTokenFromGhCli();
+    const token = readGithubTokenFromEnv();
+    return token !== undefined ? token || undefined : readGithubTokenFromGhCli();
 }
 /**
  * Build headers for GitHub API requests.

package/dist/src/llm/embedders/remote.js

@@ -5,7 +5,11 @@
  * vectors so the scoring pipeline's L2-to-cosine conversion is correct.
  */
 import { fetchWithTimeout, isHttpUrl } from "../../core/common";
-const REMOTE_BATCH_SIZE = 100;
+const DEFAULT_REMOTE_BATCH_SIZE = 100;
+/** Cheap token estimator: 4 chars ≈ 1 token. Used in verbose logging and error messages. */
+export function estimateTokenCount(text) {
+    return Math.round(text.length / 4);
+}
 export class RemoteEmbedder {
     config;
     constructor(config) {
@@ -20,6 +24,10 @@ export class RemoteEmbedder {
         if (this.config.dimension) {
             body.dimensions = this.config.dimension;
         }
+        const ollamaOpts = resolveOllamaOptions(this.config);
+        if (ollamaOpts) {
+            body.options = ollamaOpts;
+        }
         const response = await fetchWithTimeout(normalizeEmbeddingEndpoint(this.config.endpoint), {
             method: "POST",
             headers,
@@ -40,8 +48,10 @@ export class RemoteEmbedder {
             return [];
         const results = [];
         const headers = this.buildHeaders();
-        for (let i = 0; i < texts.length; i += REMOTE_BATCH_SIZE) {
-            const batch = texts.slice(i, i + REMOTE_BATCH_SIZE);
+        const ollamaOpts = resolveOllamaOptions(this.config);
+        const batchSize = this.config.batchSize ?? DEFAULT_REMOTE_BATCH_SIZE;
+        for (let i = 0; i < texts.length; i += batchSize) {
+            const batch = texts.slice(i, i + batchSize);
             const body = {
                 input: batch,
                 model: this.config.model,
@@ -49,6 +59,9 @@ export class RemoteEmbedder {
             if (this.config.dimension) {
                 body.dimensions = this.config.dimension;
             }
+            if (ollamaOpts) {
+                body.options = ollamaOpts;
+            }
             const response = await fetchWithTimeout(normalizeEmbeddingEndpoint(this.config.endpoint), {
                 method: "POST",
                 headers,
@@ -115,6 +128,27 @@ function embeddingEndpointPathHint(endpoint) {
     }
     return "";
 }
+/**
+ * Resolve Ollama-native `options` from the embedding config.
+ *
+ * Resolution order:
+ *   1. `ollamaOptions` — forwarded verbatim (explicit opt-in, takes precedence).
+ *   2. `contextLength` — wrapped as `{ num_ctx: contextLength }`.
+ *   3. Neither set → returns `undefined` (no `options` field in the request body).
+ *
+ * These options are only meaningful for Ollama's native `/api/embed` endpoint.
+ * OpenAI-compatible endpoints ignore unknown request fields, so passing them to
+ * other providers is harmless but has no effect.
+ */
+function resolveOllamaOptions(config) {
+    if (config.ollamaOptions && Object.keys(config.ollamaOptions).length > 0) {
+        return config.ollamaOptions;
+    }
+    if (config.contextLength) {
+        return { num_ctx: config.contextLength };
+    }
+    return undefined;
+}
 /** Check whether an EmbeddingConnectionConfig has a valid remote endpoint. */
 export function hasRemoteEndpoint(config) {
     return isHttpUrl(config.endpoint);

package/dist/src/output/cli-hints.js

@@ -11,6 +11,19 @@ const EMBEDDED_HINTS = `# akm CLI
 
 You have access to a searchable library of scripts, skills, commands, agents, knowledge documents, workflows, wikis, and memories via \`akm\`. Search your sources first before writing something from scratch.
 
+## Agent Task Loop
+
+For any task, follow this loop:
+1. \`akm curate "<task>"\` — find the best matching asset
+2. \`akm show <ref>\` — read the schema (field names and structure)
+3. Edit the workspace file using schema field names + task-specific values from your README
+4. \`akm feedback <ref> --positive\` — record success
+
+For workflow tasks:
+1. \`akm workflow next workflow:<name>\` — get current step instructions
+2. Do the step work in your workspace
+3. \`akm workflow complete <run-id> --step <step-id>\` — mark done, get next step
+
 ## Quick Reference
 
 \`\`\`sh
@@ -144,7 +157,7 @@ akm wiki list                                  # List wikis (name, pages, raws,
 akm wiki create research                       # Scaffold a new wiki
 akm wiki register ics-docs ~/code/ics-documentation # Register an external wiki
 akm wiki show research                         # Path, description, counts, last 3 log entries
-akm wiki pages research                        # Page refs + descriptions (excludes schema/index/log/raw)
+akm wiki pages research                        # Page refs + descriptions (excludes schema/index/log; includes raw/)
 akm wiki search research "attention"           # Scoped search (equivalent to --type wiki --wiki research)
 akm wiki stash research ./paper.md             # Copy source into raw/<slug>.md (never overwrites)
 echo "..." | akm wiki stash research -         # stdin form
@@ -254,7 +267,7 @@ akm registry add <url> --provider skills-sh   # Specify provider type
 akm registry remove <url-or-name>             # Remove a registry
 akm registry search "<query>"                 # Search all registries
 akm registry search "<query>" --assets        # Include asset-level results
-akm registry build-index                      # Build ./index.json
+akm registry build-index                      # Build the default cache-backed index.json
 akm registry build-index --out dist/index.json # Build to a custom path
 \`\`\`
 

package/dist/src/output/renderers.js

@@ -187,12 +187,14 @@ const skillMdRenderer = {
     name: "skill-md",
     buildShowResponse(ctx) {
         const name = deriveName(ctx);
+        const parsed = parseFrontmatter(ctx.content());
         return {
             type: "skill",
             name,
             path: ctx.absPath,
             action: "Read and follow the instructions below",
-            content: ctx.content(),
+            description: toStringOrUndefined(parsed.data.description),
+            content: parsed.content,
         };
     },
 };

package/dist/src/output/shapes.js

@@ -293,6 +293,10 @@ export function shapeHistoryOutput(result, detail) {
             ...(result.since !== undefined ? { since: result.since } : {}),
             totalCount: result.totalCount ?? shapedEntries.length,
             entries: shapedEntries,
+            // `sources` lists the event sources included in this response.
+            // Always contains "usage_events"; also "events.jsonl" when
+            // --include-proposals was specified.
+            ...(Array.isArray(result.sources) ? { sources: result.sources } : {}),
             ...(Array.isArray(result.warnings) && result.warnings.length > 0 ? { warnings: result.warnings } : {}),
         };
     }
@@ -301,6 +305,7 @@ export function shapeHistoryOutput(result, detail) {
         ...(result.since !== undefined ? { since: result.since } : {}),
         totalCount: result.totalCount ?? shapedEntries.length,
         entries: shapedEntries,
+        ...(Array.isArray(result.sources) ? { sources: result.sources } : {}),
         ...(Array.isArray(result.warnings) && result.warnings.length > 0 ? { warnings: result.warnings } : {}),
     };
 }
@@ -399,8 +404,10 @@ export function shapeSearchHit(hit, detail) {
         return hit;
     }
     // Stash hit (local or remote)
+    // `ref` is included at `brief` so agents can run `akm show <ref>` without
+    // needing --detail full or --for-agent (REC-03).
     if (detail === "brief")
-        return pickFields(hit, ["type", "name", "action", "estimatedTokens"]);
+        return pickFields(hit, ["type", "name", "ref", "action", "estimatedTokens"]);
     if (detail === "normal") {
         // `warnings` is projected at `normal` so non-fatal hit-level issues are
         // visible without forcing callers up to `--detail full`. Optional