akm-cli 0.9.0-beta.9 → 0.9.0-rc.0

package/dist/integrations/agent/prompts.js

@@ -26,6 +26,7 @@
  * during validation. We carry it through if the agent supplies it.
  */
 import { TYPE_DIRS } from "../../core/asset/asset-spec.js";
+import { authoringRulesForType, DESCRIPTION_MAX_CHARS, DESCRIPTION_MIN_CHARS, requiresDescription, } from "../../core/authoring-rules.js";
 import { parseEmbeddedJsonResponse, stripCodeFences, stripThinkBlocks } from "../../core/parse.js";
 /**
  * Per-asset-type frontmatter / authoring hints surfaced in the prompt so
@@ -41,8 +42,9 @@ const TYPE_HINTS = {
     memory: "memory assets are short factual notes the user wants persisted across sessions. Frontmatter usually includes `description`.",
     workflow: "workflow assets are markdown describing a multi-step process. Include `# <Title>` and ordered `## Step N` sections.",
     script: "script assets are executable text files. Include a shebang and minimal usage comment.",
-    env: "env assets are `.env` files holding a group of related CONFIGURATION for an app/service (KEY=VALUE pairs, `#` comments) — URLs, flags, and any credentials it needs. Values may or may not be sensitive; all are protected (key names discoverable, values stay on disk). Inject with `akm env run env:<name> -- <cmd>` (the safe path — values never reach stdout/your context); do NOT run `akm env export` and read its output, as that prints values. For a single sensitive value used on its own for authentication (token, key, cert) use a `secret` instead. Never echo values back to the user.",
+    env: "env assets are `.env` files holding a group of related CONFIGURATION for an app/service (KEY=VALUE pairs, `#` comments) — URLs, flags, and any credentials it needs. Values may or may not be sensitive; all are protected (key names discoverable, values stay on disk). Inject with `akm env run env:<name> -- <cmd>`; prefer `--clean` in agent contexts so the child starts from a minimal inherited environment. AKM itself does not print values, but the child command can print its environment, so do not run `env`, `printenv`, shell tracing, or similar diagnostics when secrets are in scope. For a single sensitive value used on its own for authentication (token, key, cert) use a `secret` instead. Never echo values back to the user.",
     wiki: "wiki assets are markdown reference pages with `# Title` and structured headings.",
+    fact: "fact assets are durable stash-level facts (personal/team/project details, coding conventions, stash-meta). Frontmatter SHOULD include `description` and a `category` (personal|team|project|convention|meta); set `pinned: true` only for the small always-injected core. Keep each fact short, high-signal, and self-contained — it is durable context, not an episodic note.",
 };
 function hintForType(type) {
     return TYPE_HINTS[type] ?? `assets of type "${type}" — produce sensible markdown with optional frontmatter.`;
@@ -109,6 +111,30 @@ export function extractDraftConfidence(stdout) {
         return undefined;
     return value;
 }
+/**
+ * Whether the source asset content has a non-empty `description:` key in its
+ * YAML frontmatter. Used by {@link buildReflectPrompt} (#636) to decide whether
+ * to inject the synthesize-a-description instruction. Uses an inline regex to
+ * avoid pulling the full YAML parser into the prompt module (mirrors the
+ * existing inline frontmatter handling here).
+ */
+function sourceHasNonEmptyDescription(assetContent) {
+    if (!assetContent)
+        return false;
+    const fmMatch = assetContent.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+    if (!fmMatch)
+        return false;
+    const fmBlock = fmMatch[1] ?? "";
+    // Match a top-level `description:` line and capture its inline value.
+    const descMatch = fmBlock.match(/^description\s*:\s*(.*)$/m);
+    if (!descMatch)
+        return false;
+    const value = (descMatch[1] ?? "")
+        .trim()
+        .replace(/^['"]|['"]$/g, "")
+        .trim();
+    return value.length > 0;
+}
 /**
  * Build the prompt for `akm reflect [ref]`. Asks the agent to review an
  * existing asset (plus any negative feedback / lint findings) and propose
@@ -155,6 +181,34 @@ export function buildReflectPrompt(input) {
         // ref is set but no feedback — explicitly constrain scope to schema compliance
         sections.push("No usage feedback recorded. Limit your proposal to schema and structural improvements only: missing required frontmatter fields, unclear `when_to_use`, ambiguous description, or broken formatting. Do not speculate about runtime weaknesses you have not observed.");
     }
+    if (input.standardsContext?.trim()) {
+        sections.push("Standards to follow (the rulebook for this target):");
+        sections.push(input.standardsContext.trim());
+    }
+    {
+        const resolvedType = input.type ?? (input.ref?.includes(":") ? input.ref.split(":")[0] : "");
+        const authoringRules = resolvedType ? authoringRulesForType(resolvedType) : "";
+        if (authoringRules) {
+            sections.push(authoringRules);
+        }
+        // #636 — synthesize-a-description instruction. Many source assets (notably
+        // scraped docs: `source`/`title`/`scraped`) carry frontmatter but NO
+        // `description`. Reflect echoes the source frontmatter, so the proposal
+        // inherits the missing description and the promote-time validator
+        // (isValidDescription, 20–400 chars) rejects it. The fix is at GENERATION
+        // time: when the source lacks a non-empty `description` and the type
+        // requires one, tell the model — unmissably — that it MUST author a valid
+        // `description`. (The validator/promote path is NOT changed: it must never
+        // fabricate content to pass itself.)
+        if (resolvedType && requiresDescription(resolvedType) && !sourceHasNonEmptyDescription(input.assetContent)) {
+            sections.push([
+                "REQUIRED — synthesize a `description` (the source asset has none):",
+                `- The source frontmatter does NOT include a non-empty \`description\`, but a ${resolvedType} asset REQUIRES one or the proposal will be rejected at promote time.`,
+                `- You MUST author a valid \`description\` in the proposal frontmatter: ${DESCRIPTION_MIN_CHARS}–${DESCRIPTION_MAX_CHARS} characters of plain-prose sentence summarizing what this asset is about.`,
+                '- Synthesize it from the asset\'s `title:` frontmatter, its first `# Heading`, or the opening body sentence. Do NOT copy a bare heading fragment (e.g. "Overview", "Named Page", "Key Insight") and do NOT emit a truncated phrase that ends on `:`/`;`/`,` or a hanging connector word.',
+            ].join("\n"));
+        }
+    }
     if (input.assetContent?.trim()) {
         // Cap at 12 000 chars to stay well under OS ARG_MAX when the prompt is
         // passed as a CLI argument to opencode/claude. Large assets (wiki snapshots,
@@ -288,6 +342,16 @@ export function buildProposePrompt(input) {
         for (const line of input.schemaHints)
             sections.push(`- ${line}`);
     }
+    if (input.standardsContext?.trim()) {
+        sections.push("Standards to follow (the rulebook for this target):");
+        sections.push(input.standardsContext.trim());
+    }
+    {
+        const authoringRules = authoringRulesForType(input.type);
+        if (authoringRules) {
+            sections.push(authoringRules);
+        }
+    }
     sections.push("Produce a single proposal that, if accepted, would land as the asset described above.");
     sections.push(input.draftFilePath ? fileWriteContract(input.draftFilePath) : RESPONSE_CONTRACT_JSON);
     return sections.join("\n\n");
@@ -304,6 +368,16 @@ export function buildSchemaRepairPrompt(input) {
         `while preserving all existing content.`);
     sections.push(`Target ref: ${input.ref}`);
     sections.push(`Schema requirements for ${input.type} assets: ${hintForType(input.type)}`);
+    if (input.standardsContext?.trim()) {
+        sections.push("Standards to follow (the rulebook for this target):");
+        sections.push(input.standardsContext.trim());
+    }
+    {
+        const authoringRules = authoringRulesForType(input.type);
+        if (authoringRules) {
+            sections.push(authoringRules);
+        }
+    }
     const CONTENT_CAP = 3000;
     const body = input.assetContent.trimEnd();
     const truncated = body.length > CONTENT_CAP;
@@ -370,11 +444,3 @@ export function parseAgentProposalPayload(stdout) {
     }
     return out;
 }
-/**
- * Strip `\`\`\`json … \`\`\`` fences and `<think>…</think>` reasoning blocks
- * from agent output. Thin wrapper around `core/parse` helpers, kept exported
- * for backward compatibility (re-exported from `integrations/agent/index.ts`).
- */
-export function stripJsonFences(text) {
-    return stripCodeFences(stripThinkBlocks(text));
-}

package/dist/integrations/agent/runner-dispatch.js

@@ -0,0 +1,59 @@
+// 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/.
+/**
+ * X3 — the ONE dispatch seam for the {@link RunnerSpec} tagged union.
+ *
+ * The improve slice dispatches a `RunnerSpec` (`llm | agent | sdk`) in several
+ * places (`reflect.ts`, `proposal/drain.ts`, …). Before this module each site
+ * re-rolled the identical 3-arm switch and re-declared its own per-kind test
+ * seams (`chat`, `runAgentFn`, `runSdkFn`). `executeRunner` collapses that into
+ * one switch + one {@link RunnerSeams} object.
+ *
+ * Scoping (behavior-preserving):
+ *   - The `agent` and `sdk` arms are byte-identical across call sites: invoke
+ *     the profile runner (`runAgent` / `runOpencodeSdk`) with the per-call
+ *     `RunAgentOptions` the caller passes. Those default runners live here so
+ *     callers stop importing `runAgent` / `runOpencodeSdk` for dispatch. The
+ *     `opts` (incl. any `timeoutMs`) is constructed by the caller and passed
+ *     through unchanged, so each site keeps its exact option set.
+ *   - The `llm` arm is irreducibly caller-specific (reflect wraps
+ *     `runReflectViaLlm`, which returns reflect's iteration shape; drain wraps a
+ *     plain `chatCompletion`). It is therefore a REQUIRED seam — there is no
+ *     default `llm` handler — so neither caller's bespoke behavior is changed.
+ *   - The `assertNever` exhaustiveness arm is kept so a 4th `RunnerSpec` kind is
+ *     a compile error here instead of a silent runtime fall-through.
+ *
+ * The return type is {@link AgentRunResult} so a later `callStructured` layer
+ * (X2) can wrap `executeRunner` without changing this contract.
+ */
+import { assertNever } from "../../core/assert.js";
+import { runOpencodeSdk } from "../harnesses/opencode-sdk/index.js";
+import { runAgent } from "./spawn.js";
+/**
+ * Dispatch a {@link RunnerSpec} to its runner and return the raw
+ * {@link AgentRunResult}. `opts` is the {@link RunAgentOptions} for the profile
+ * (`agent` / `sdk`) arms; it is passed through unchanged so each caller keeps
+ * its exact option set (incl. any `timeoutMs` the caller chose to apply).
+ */
+export async function executeRunner(spec, prompt, opts, seams = {}) {
+    switch (spec.kind) {
+        case "llm": {
+            if (!seams.llm) {
+                throw new Error("executeRunner: an `llm` runner requires a `seams.llm` handler (no default LLM dispatch).");
+            }
+            return seams.llm(spec, prompt);
+        }
+        case "agent": {
+            const run = seams.runAgent ?? runAgent;
+            return run(spec.profile, prompt, opts);
+        }
+        case "sdk": {
+            const run = seams.runSdk ?? runOpencodeSdk;
+            return run(spec.profile, prompt, opts);
+        }
+        default:
+            // Exhaustiveness arm: a 4th RunnerSpec kind becomes a compile error here.
+            return assertNever(spec);
+    }
+}

package/dist/integrations/agent/runner.js

@@ -157,6 +157,19 @@ function resolveProcessRunnerWithLlmFallback(block, config, opts) {
     }
     return null;
 }
+/**
+ * Build the tool-less HTTP runner from `defaults.llm`, or `null` when unset.
+ * The unattended-improve reflect pin (meta-review 07 Chain-G / P1.3) uses this
+ * as the mandatory downgrade target when config would otherwise hand reflect a
+ * tool-capable (agent/SDK) runner in a scheduled run. Throws ConfigError when
+ * `defaults.llm` names a profile that does not exist.
+ */
+export function resolveDefaultLlmRunner(config, timeoutMs) {
+    const name = config.defaults?.llm;
+    if (!name)
+        return null;
+    return buildLlmRunnerSpec(name, timeoutMs, config);
+}
 export function resolveValidationRunner(config) {
     const validation = config.profiles?.improve?.default?.processes?.validation;
     const block = validation && validation.enabled !== false ? validation : undefined;
@@ -213,15 +226,6 @@ export function resolveImproveProcessRunnerFromProfile(processConfig, config) {
     }
     return null;
 }
-/**
- * Convenience accessor for callers that previously read
- * `getProcessOptions("index", "staleness_detection", config).thresholdDays`.
- * After the 0.8.0 migration, those values live on first-class config keys —
- * see `config.index?.stalenessDetection?.thresholdDays` etc.
- */
-export function getStalenessDetectionThresholdDays(config) {
-    return config.index?.stalenessDetection?.thresholdDays;
-}
 // Re-export `isProcessEnabled` from feature-gate.ts so callers that previously
 // imported it from runner.ts continue to work.
 export { isProcessEnabled } from "../../llm/feature-gate.js";

package/dist/integrations/agent/spawn.js

@@ -17,6 +17,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { parseEmbeddedJsonResponse } from "../../core/parse.js";
 import { spawn as runtimeSpawn } from "../../runtime.js";
 import { getCommandBuilder } from "./builders.js";
 import { DEFAULT_AGENT_TIMEOUT_MS } from "./config.js";
@@ -203,6 +204,19 @@ export async function runAgent(profile, prompt, options = {}) {
     const finalArgv = [...builtArgv, ...(options.dispatch ? (options.args ?? []) : [])];
     const env = { ...buildChildEnv(profile, options), ...(builtEnv ?? {}) };
     const start = Date.now();
+    // Cooperative cancel: refuse to spawn at all when the caller's signal is
+    // already aborted (e.g. the run's budget was exhausted before this unit).
+    if (options.signal?.aborted) {
+        return {
+            ok: false,
+            exitCode: null,
+            stdout: "",
+            stderr: "",
+            durationMs: 0,
+            reason: "aborted",
+            error: `agent CLI "${profile.name}" not started: caller signal already aborted`,
+        };
+    }
     let proc;
     try {
         const spawnFn = resolveSpawnFn(options);
@@ -211,7 +225,9 @@ export async function runAgent(profile, prompt, options = {}) {
             stdout: stdioMode === "captured" ? "pipe" : "inherit",
             stderr: stdioMode === "captured" ? "pipe" : "inherit",
             env,
-            ...(options.cwd ? { cwd: options.cwd } : {}),
+            // options.cwd wins; dispatch.cwd is the request-level fallback (it was
+            // declared on AgentDispatchRequest but consumed by nothing — P0.5 fix).
+            ...((options.cwd ?? options.dispatch?.cwd) ? { cwd: options.cwd ?? options.dispatch?.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
@@ -258,6 +274,31 @@ export async function runAgent(profile, prompt, options = {}) {
             }, 5000);
         }, timeoutMs);
     }
+    // Cooperative cancel: same SIGTERM→SIGKILL discipline as the timeout, but
+    // flagged separately so the result carries `reason: "aborted"`.
+    let aborted = false;
+    const abortSignal = options.signal;
+    const onAbort = () => {
+        if (!proc || proc.exitCode !== null)
+            return;
+        aborted = true;
+        killGroup(proc, "SIGTERM");
+        const sigkillTimer = setTimeoutImpl(() => {
+            if (!proc || proc.exitCode !== null)
+                return;
+            killGroup(proc, "SIGKILL");
+        }, 5000);
+        if (typeof sigkillTimer !== "number")
+            sigkillTimer.unref?.();
+    };
+    if (abortSignal) {
+        // A signal that aborted between the pre-spawn check and here is handled
+        // by calling the listener directly.
+        if (abortSignal.aborted)
+            onAbort();
+        else
+            abortSignal.addEventListener("abort", onAbort, { once: true });
+    }
     // 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
@@ -304,6 +345,7 @@ export async function runAgent(profile, prompt, options = {}) {
     catch (err) {
         if (timer !== undefined)
             clearTimeoutImpl(timer);
+        abortSignal?.removeEventListener("abort", onAbort);
         // 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
@@ -321,8 +363,20 @@ export async function runAgent(profile, prompt, options = {}) {
         };
     }
     clearTimeoutImpl(timer);
+    abortSignal?.removeEventListener("abort", onAbort);
     const [stdout, stderr] = await Promise.all([stdoutPromise, stderrPromise]);
     const durationMs = Date.now() - start;
+    if (aborted) {
+        return {
+            ok: false,
+            exitCode,
+            stdout,
+            stderr,
+            durationMs,
+            reason: "aborted",
+            error: `agent CLI "${profile.name}" aborted by caller signal`,
+        };
+    }
     if (timedOut) {
         return {
             ok: false,
@@ -346,72 +400,20 @@ export async function runAgent(profile, prompt, options = {}) {
         };
     }
     if (parseOutput === "json" && stdioMode === "captured") {
-        // Strip <think> blocks and code fences, then try direct parse with
-        // embedded-JSON fallback for local LLMs that emit prose around the payload.
-        const cleaned = stdout
-            .trim()
-            .replace(/<think>[\s\S]*?<\/think>/gi, "")
-            .trim()
-            .replace(/^```(?:json)?\s*\n?/, "")
-            .replace(/\n?```\s*$/, "")
-            .trim();
-        let parsed;
-        try {
-            parsed = JSON.parse(cleaned);
-        }
-        catch {
-            // Fallback: extract the first balanced {…} from prose output.
-            let found;
-            for (let s = 0; s < cleaned.length; s++) {
-                if (cleaned[s] !== "{")
-                    continue;
-                let depth = 0, inStr = false, esc = false;
-                for (let i = s; i < cleaned.length; i++) {
-                    const c = cleaned[i];
-                    if (inStr) {
-                        if (esc) {
-                            esc = false;
-                        }
-                        else if (c === "\\") {
-                            esc = true;
-                        }
-                        else if (c === '"') {
-                            inStr = false;
-                        }
-                        continue;
-                    }
-                    if (c === '"') {
-                        inStr = true;
-                        continue;
-                    }
-                    if (c === "{")
-                        depth++;
-                    if (c === "}") {
-                        depth--;
-                        if (depth === 0) {
-                            try {
-                                found = JSON.parse(cleaned.slice(s, i + 1));
-                            }
-                            catch { }
-                            break;
-                        }
-                    }
-                }
-                if (found !== undefined)
-                    break;
-            }
-            if (found === undefined) {
-                return {
-                    ok: false,
-                    exitCode,
-                    stdout,
-                    stderr,
-                    durationMs,
-                    reason: "parse_error",
-                    error: "no JSON object found in agent output",
-                };
-            }
-            parsed = found;
+        // Strip <think> blocks and code fences, then parse with embedded-JSON
+        // fallback for local LLMs that emit prose around the payload. Handles
+        // both top-level `{…}` and `[…]` structures.
+        const parsed = parseEmbeddedJsonResponse(stdout);
+        if (parsed === undefined) {
+            return {
+                ok: false,
+                exitCode,
+                stdout,
+                stderr,
+                durationMs,
+                reason: "parse_error",
+                error: "no JSON structure found in agent output",
+            };
         }
         return { ok: true, exitCode, stdout, stderr, durationMs, parsed };
     }

package/dist/integrations/harnesses/claude/agent-builder.js

@@ -33,7 +33,7 @@ export const claudeBuilder = {
             args.push("--system-prompt", req.systemPrompt);
         }
         if (req.model) {
-            const resolved = resolveModel(req.model, "claude", profile.modelAliases);
+            const resolved = resolveModel(req.model, "claude", profile.modelAliases, profile.globalModelAliases);
             args.push("--model", resolved);
         }
         if (req.tools) {

package/dist/integrations/harnesses/claude/index.js

@@ -25,6 +25,7 @@
  * that say `'claude-code'` keep working unchanged.
  */
 import { BaseHarness } from "../types.js";
+import { claudeBuilder } from "./agent-builder.js";
 export { claudeBuilder } from "./agent-builder.js";
 export { claudeCodeImporter } from "./config-import.js";
 export { ClaudeCodeProvider } from "./session-log.js";
@@ -53,6 +54,7 @@ export class ClaudeHarness extends BaseHarness {
     // Home-relative config dir scanned by `akm setup` (#567). Claude Code has a
     // session-log provider, so offering it as a stash source is functional.
     setupDetectionDir = ".claude";
+    agentBuilder = claudeBuilder;
     capabilities = caps({
         sessionLogs: true,
         agentDispatch: true,

package/dist/integrations/harnesses/claude/session-log.js

@@ -107,6 +107,16 @@ export class ClaudeCodeProvider {
     isAvailable() {
         return fs.existsSync(claudeProjectsDir());
     }
+    /**
+     * Directory holding Claude Code's per-project session JSONL files
+     * (`~/.claude/projects`, honoring `AKM_CLAUDE_PROJECTS_DIR`). Returns `[]`
+     * when the directory does not exist on this machine. See {@link
+     * SessionLogHarness.watchRoots}.
+     */
+    watchRoots() {
+        const dir = claudeProjectsDir();
+        return fs.existsSync(dir) ? [dir] : [];
+    }
     *readEvents(input) {
         try {
             for (const jsonlPath of this.#walkJsonl(claudeProjectsDir())) {

package/dist/integrations/harnesses/index.js

@@ -60,9 +60,8 @@ const HARNESS_BY_ANY_ID = (() => {
 })();
 /**
  * Canonical, ordered list of valid harness / platform ids. The Zod
- * `AgentPlatformSchema` enum, the `AgentProfileConfigV2` platform union,
- * `parseAgentProfilesMapV2`'s membership check, and setup's `DetectedHarness`
- * union all derive from this so they cannot drift.
+ * `AgentPlatformSchema` enum, the `AgentProfileConfig` platform union, and
+ * setup's `DetectedHarness` union all derive from this so they cannot drift.
  */
 export const VALID_HARNESS_IDS = Object.freeze(HARNESS_REGISTRY.map((h) => h.id));
 /** Harnesses that expose readable native session logs. */

package/dist/integrations/harnesses/opencode/agent-builder.js

@@ -33,7 +33,7 @@ export const opencodeBuilder = {
             args.push("--system-prompt", req.systemPrompt);
         }
         if (req.model) {
-            const resolved = resolveModel(req.model, "opencode", profile.modelAliases);
+            const resolved = resolveModel(req.model, "opencode", profile.modelAliases, profile.globalModelAliases);
             args.push("--model", resolved);
         }
         args.push("--");

package/dist/integrations/harnesses/opencode/index.js

@@ -18,6 +18,7 @@
  * Claude Code's 'claude' vs 'claude-code'), so no alias bridge is needed.
  */
 import { BaseHarness } from "../types.js";
+import { opencodeBuilder } from "./agent-builder.js";
 export { opencodeBuilder } from "./agent-builder.js";
 export { openCodeImporter } from "./config-import.js";
 export { OpenCodeProvider } from "./session-log.js";
@@ -48,6 +49,7 @@ export class OpencodeHarness extends BaseHarness {
     // `v1ProfilePlatform()` resolves most-specific-id-first, so "opencode-sdk-*"
     // is claimed by OpencodeSdkHarness before this prefix can over-match it.
     v1ProfilePrefixes = ["opencode"];
+    agentBuilder = opencodeBuilder;
     capabilities = caps({
         sessionLogs: true,
         agentDispatch: true,