akm-cli 0.7.4 → 0.8.0-rc.3

package/dist/integrations/agent/config.js

@@ -27,14 +27,30 @@ import { ConfigError } from "../../core/errors";
 import { warn } from "../../core/warn";
 import { BUILTIN_AGENT_PROFILE_NAMES, getBuiltinAgentProfile, listBuiltinAgentProfiles, } from "./profiles";
 /** Keys recognised at the top level of an `agent` config block. */
-const KNOWN_AGENT_KEYS = new Set(["default", "timeoutMs", "profiles"]);
+const KNOWN_AGENT_KEYS = new Set(["default", "timeoutMs", "profiles", "processes"]);
 /** Keys recognised on a profile entry. */
-const KNOWN_PROFILE_KEYS = new Set(["bin", "args", "stdio", "env", "envPassthrough", "timeoutMs", "parseOutput"]);
+const KNOWN_PROFILE_KEYS = new Set([
+    "bin",
+    "args",
+    "stdio",
+    "env",
+    "envPassthrough",
+    "timeoutMs",
+    "parseOutput",
+    "sdkMode",
+    "model",
+    "endpoint",
+    "apiKey",
+    "commandBuilder",
+    "modelAliases",
+]);
 /**
  * Default hard timeout for an agent CLI. Spec §12.2 calls for a hard
  * timeout; 60s matches the example value in `docs/configuration.md`.
  */
 export const DEFAULT_AGENT_TIMEOUT_MS = 60_000;
+/** Keys recognised on a `processes[<name>]` object entry. */
+const KNOWN_PROCESS_ENTRY_KEYS = new Set(["profile", "timeoutMs"]);
 /**
  * Parse a raw value (typically `rawConfig.agent` from `JSON.parse`) into a
  * normalised {@link AgentConfig}. Returns `undefined` when the value is not
@@ -83,6 +99,11 @@ export function parseAgentConfig(value) {
         if (profiles)
             out.profiles = profiles;
     }
+    if ("processes" in raw) {
+        const processes = parseProcessesMap(raw.processes);
+        if (processes)
+            out.processes = processes;
+    }
     return out;
 }
 function parseAgentProfilesMap(value) {
@@ -98,6 +119,124 @@ function parseAgentProfilesMap(value) {
     }
     return Object.keys(out).length > 0 ? out : undefined;
 }
+/**
+ * Parse one entry in `agent.processes`. Accepts a string (profile name) or an
+ * object with optional `profile` and `timeoutMs` fields. Returns `undefined`
+ * and emits a warning for entries that are neither valid strings nor valid
+ * objects (warn-and-ignore).
+ */
+export function parseProcessEntry(value, name) {
+    if (typeof value === "string") {
+        if (!value.trim()) {
+            warn(`[akm] Ignoring agent.processes."${name}": string value must be non-empty (a profile name).`);
+            return undefined;
+        }
+        return value.trim();
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        warn(`[akm] Ignoring agent.processes."${name}": expected a string (profile name) or an object with optional "profile" and "timeoutMs".`);
+        return undefined;
+    }
+    const raw = value;
+    // Warn on unknown keys (warn-and-ignore contract).
+    for (const key of Object.keys(raw)) {
+        if (!KNOWN_PROCESS_ENTRY_KEYS.has(key)) {
+            warn(`[akm] Ignoring unknown agent.processes."${name}" key: "${key}"`);
+        }
+    }
+    const out = {};
+    if ("profile" in raw) {
+        if (typeof raw.profile === "string" && raw.profile.trim()) {
+            out.profile = raw.profile.trim();
+        }
+        else if (raw.profile !== undefined) {
+            warn(`[akm] Ignoring agent.processes."${name}".profile: expected a non-empty string.`);
+        }
+    }
+    if ("timeoutMs" in raw) {
+        if (raw.timeoutMs === null) {
+            // null = unlimited — explicit, valid.
+            out.timeoutMs = null;
+        }
+        else if (typeof raw.timeoutMs === "number" &&
+            Number.isFinite(raw.timeoutMs) &&
+            Number.isInteger(raw.timeoutMs) &&
+            raw.timeoutMs > 0) {
+            out.timeoutMs = raw.timeoutMs;
+        }
+        else {
+            warn(`[akm] Ignoring agent.processes."${name}".timeoutMs: expected a positive integer (milliseconds) or null (unlimited).`);
+        }
+    }
+    return out;
+}
+/**
+ * Parse the `agent.processes` map. Returns `undefined` when the value is not
+ * a valid object; per-entry validation errors are warn-and-ignored (per spec §9.2).
+ */
+export function parseProcessesMap(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        warn("[akm] Ignoring agent.processes: expected an object.");
+        return undefined;
+    }
+    const out = {};
+    for (const [name, raw] of Object.entries(value)) {
+        const parsed = parseProcessEntry(raw, name);
+        if (parsed !== undefined)
+            out[name] = parsed;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/**
+ * Resolve the agent profile and effective timeout for a named process.
+ *
+ * Resolution order:
+ * 1. `config.processes[processName]` — if a string, that is the profile name;
+ *    if an object, extract `profile` (and optionally `timeoutMs`).
+ * 2. Profile name falls back to `config.default` when not specified in the
+ *    process entry.
+ * 3. `timeoutMs` falls back: `process.timeoutMs` (null = unlimited) →
+ *    profile.timeoutMs → agent.timeoutMs → DEFAULT_AGENT_TIMEOUT_MS.
+ *
+ * Returns `{ profile, timeoutMs }` where `timeoutMs` is `undefined` when the
+ * resolved timeout is `null` (unlimited) or when no timeout is set at any
+ * layer (callers treat `undefined` as the DEFAULT_AGENT_TIMEOUT_MS default).
+ *
+ * Throws {@link ConfigError} (via {@link requireAgentProfile}) when the agent
+ * block is missing or the resolved profile cannot be used.
+ */
+export function resolveProcessAgentProfile(processName, agentConfig) {
+    let profileName;
+    let processTimeoutMs; // null = unlimited from config
+    const processEntry = agentConfig?.processes?.[processName];
+    if (processEntry !== undefined) {
+        if (typeof processEntry === "string") {
+            profileName = processEntry;
+        }
+        else {
+            profileName = processEntry.profile;
+            processTimeoutMs = processEntry.timeoutMs;
+        }
+    }
+    // Profile name falls back to agent.default when not set in the process entry.
+    const resolvedProfile = requireAgentProfile(agentConfig, profileName);
+    // Timeout resolution: process entry → profile → agent-level → undefined (caller applies DEFAULT).
+    let resolvedTimeoutMs;
+    if (processTimeoutMs === null) {
+        // null = explicit "unlimited" — surface as undefined so callers omit the timer.
+        resolvedTimeoutMs = undefined;
+    }
+    else if (processTimeoutMs !== undefined) {
+        resolvedTimeoutMs = processTimeoutMs;
+    }
+    else if (resolvedProfile.timeoutMs !== undefined) {
+        resolvedTimeoutMs = resolvedProfile.timeoutMs;
+    }
+    else if (agentConfig?.timeoutMs !== undefined) {
+        resolvedTimeoutMs = agentConfig.timeoutMs;
+    }
+    return { profile: resolvedProfile, timeoutMs: resolvedTimeoutMs };
+}
 function parseAgentProfileConfig(name, value) {
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
         warn(`[akm] Ignoring agent.profiles."${name}": expected an object.`);
@@ -171,6 +310,52 @@ function parseAgentProfileConfig(name, value) {
     else if (raw.parseOutput !== undefined) {
         warn(`[akm] Ignoring agent.profiles."${name}".parseOutput: expected "text" or "json".`);
     }
+    if (raw.sdkMode === true || raw.sdkMode === false) {
+        out.sdkMode = raw.sdkMode;
+    }
+    else if (raw.sdkMode !== undefined) {
+        warn(`[akm] Ignoring agent.profiles."${name}".sdkMode: expected a boolean.`);
+    }
+    if (typeof raw.model === "string" && raw.model.trim()) {
+        out.model = raw.model.trim();
+    }
+    else if (raw.model !== undefined) {
+        warn(`[akm] Ignoring agent.profiles."${name}".model: expected a non-empty string.`);
+    }
+    if (typeof raw.endpoint === "string" && raw.endpoint.trim()) {
+        out.endpoint = raw.endpoint.trim();
+    }
+    else if (raw.endpoint !== undefined) {
+        warn(`[akm] Ignoring agent.profiles."${name}".endpoint: expected a non-empty string.`);
+    }
+    if (typeof raw.apiKey === "string" && raw.apiKey.trim()) {
+        out.apiKey = raw.apiKey.trim();
+    }
+    else if (raw.apiKey !== undefined) {
+        warn(`[akm] Ignoring agent.profiles."${name}".apiKey: expected a non-empty string.`);
+    }
+    if (typeof raw.commandBuilder === "string" && raw.commandBuilder.trim()) {
+        out.commandBuilder = raw.commandBuilder.trim();
+    }
+    else if (raw.commandBuilder !== undefined) {
+        warn(`[akm] Ignoring agent.profiles."${name}".commandBuilder: expected a non-empty string.`);
+    }
+    if (typeof raw.modelAliases === "object" && raw.modelAliases !== null && !Array.isArray(raw.modelAliases)) {
+        const aliases = {};
+        for (const [k, v] of Object.entries(raw.modelAliases)) {
+            if (typeof v === "string") {
+                aliases[k.toLowerCase()] = v;
+            }
+            else {
+                warn(`[akm] Ignoring non-string value for agent.profiles."${name}".modelAliases key "${k}".`);
+            }
+        }
+        if (Object.keys(aliases).length > 0)
+            out.modelAliases = aliases;
+    }
+    else if (raw.modelAliases !== undefined) {
+        warn(`[akm] Ignoring agent.profiles."${name}".modelAliases: expected a string-valued object.`);
+    }
     return out;
 }
 /**
@@ -184,7 +369,7 @@ function parseAgentProfileConfig(name, value) {
  */
 export function resolveAgentProfile(name, overrides) {
     const builtin = getBuiltinAgentProfile(name);
-    if (!builtin && !overrides?.bin)
+    if (!builtin && !overrides?.bin && overrides?.sdkMode !== true)
         return undefined;
     const base = builtin ??
         {
@@ -208,6 +393,14 @@ export function resolveAgentProfile(name, overrides) {
             : base.envPassthrough,
         timeoutMs: overrides.timeoutMs ?? base.timeoutMs,
         parseOutput: overrides.parseOutput ?? base.parseOutput,
+        sdkMode: overrides.sdkMode ?? base.sdkMode,
+        model: overrides.model ?? base.model,
+        endpoint: overrides.endpoint ?? base.endpoint,
+        apiKey: overrides.apiKey ?? base.apiKey,
+        commandBuilder: overrides.commandBuilder ?? base.commandBuilder,
+        modelAliases: overrides.modelAliases
+            ? { ...(base.modelAliases ?? {}), ...overrides.modelAliases }
+            : base.modelAliases,
     };
     return merged;
 }
@@ -274,6 +467,13 @@ export function requireAgentProfile(agent, requested) {
     if (!profile) {
         throw new ConfigError(`agent profile "${name}" is not built-in and has no \`bin\` override.`, "INVALID_CONFIG_FILE", `Define agent.profiles."${name}".bin in config.json, or pick one of: ${listAgentProfileNames(agent).join(", ")}.`);
     }
+    // Apply the top-level agent.timeoutMs as the effective default for this
+    // profile when the profile itself has no timeout override. This makes
+    // `agent.timeoutMs` the universal fallback without requiring every
+    // profile definition in config.json to repeat it.
+    if (profile.timeoutMs === undefined && agent?.timeoutMs !== undefined) {
+        return { ...profile, timeoutMs: agent.timeoutMs };
+    }
     return profile;
 }
 /**

package/dist/integrations/agent/index.js

@@ -7,11 +7,14 @@
  *   • Types: AgentProfile, AgentConfig, AgentRunResult, AgentFailureReason.
  *   • Profiles: getBuiltinAgentProfile, listBuiltinAgentProfiles, BUILTIN_AGENT_PROFILE_NAMES.
  *   • Config: parseAgentConfig, resolveProfileFromConfig, requireAgentProfile, listResolvedAgentProfiles, listAgentProfileNames.
- *   • Spawn: runAgent.
+ *   • Spawn: runAgent. Builders: getCommandBuilder, AgentCommandBuilder, AgentDispatchRequest — platform-specific argv construction.
  *   • Detection: detectAgentCliProfiles, pickDefaultAgentProfile, defaultWhich.
  */
+export { getCommandBuilder } from "./builders";
 export { DEFAULT_AGENT_TIMEOUT_MS, listAgentProfileNames, listResolvedAgentProfiles, parseAgentConfig, requireAgentProfile, resolveAgentProfile, resolveDefaultProfileName, resolveProfileFromConfig, } from "./config";
 export { defaultWhich, detectAgentCliProfiles, pickDefaultAgentProfile } from "./detect";
+export { listBuiltinModelAliases, resolveModel } from "./model-aliases";
 export { BUILTIN_AGENT_PROFILE_NAMES, getBuiltinAgentProfile, listBuiltinAgentProfiles, } from "./profiles";
-export { buildProposePrompt, buildReflectPrompt, parseAgentProposalPayload, stripJsonFences } from "./prompts";
+export { buildProposePrompt, buildReflectPrompt, buildSchemaRepairPrompt, parseAgentProposalPayload, stripJsonFences, } from "./prompts";
+export { runAgentSdk } from "./sdk-runner";
 export { runAgent } from "./spawn";

package/dist/integrations/agent/model-aliases.js

@@ -0,0 +1,63 @@
+/**
+ * Model alias registry for agent CLI dispatch (v1 spec §12.3).
+ *
+ * Translates human-friendly aliases and cross-platform model identifiers to
+ * the exact string each agent CLI expects for its --model flag.
+ *
+ * Resolution order (highest → lowest precedence):
+ *   1. Profile-level modelAliases from config.json (user-defined)
+ *   2. Built-in alias table
+ *   3. Verbatim pass-through (caller already supplied an exact model ID)
+ */
+/**
+ * Built-in alias table. Alias keys are lowercase.
+ *
+ * Platform model string conventions:
+ *   opencode — "<provider>/<model>"  e.g. "opencode/claude-opus-4-7"
+ *   claude   — bare model name       e.g. "claude-opus-4-7"
+ *              (Claude Code also accepts its own built-in shorthands, but we
+ *               always resolve to the full name for determinism)
+ */
+const BUILTIN_ALIASES = [
+    {
+        alias: "opus",
+        platforms: {
+            claude: "claude-opus-4-7",
+            opencode: "opencode/claude-opus-4-7",
+        },
+    },
+    {
+        alias: "sonnet",
+        platforms: {
+            claude: "claude-sonnet-4-6",
+            opencode: "opencode/claude-sonnet-4-6",
+        },
+    },
+    {
+        alias: "haiku",
+        platforms: {
+            claude: "claude-haiku-4-5-20251001",
+            opencode: "opencode/claude-haiku-4-5",
+        },
+    },
+];
+/**
+ * Resolve a model alias or exact model ID to the string the target platform
+ * CLI expects for its --model flag.
+ *
+ * @param model   Raw alias ("opus") or exact model ID ("claude-opus-4-7").
+ * @param platform Builder platform name ("claude", "opencode", ...).
+ * @param custom  Profile-level aliases from config.json — take priority over builtins.
+ * @returns Resolved model string, or `model` verbatim when no alias matches.
+ */
+export function resolveModel(model, platform, custom) {
+    const key = model.toLowerCase();
+    if (custom?.[key])
+        return custom[key];
+    const entry = BUILTIN_ALIASES.find((a) => a.alias === key);
+    return entry?.platforms[platform] ?? model;
+}
+/** Return all built-in alias entries (for tests and documentation). */
+export function listBuiltinModelAliases() {
+    return BUILTIN_ALIASES;
+}

package/dist/integrations/agent/profiles.js

@@ -3,6 +3,8 @@ const COMMON_PASSTHROUGH = ["HOME", "PATH", "USER", "LANG", "LC_ALL", "TERM", "T
  * Built-in profiles for the five agent CLIs the v1 spec calls out
  * explicitly. The fields here are conservative defaults — every value is
  * overridable from user config.
+ *
+ * For headless/automation use (propose, reflect, tasks), use the '-headless' variant.
  */
 const BUILTINS = {
     opencode: {
@@ -46,15 +48,75 @@ const BUILTINS = {
         parseOutput: "text",
     },
 };
-/** Names of every built-in profile. Stable, sorted. */
+/**
+ * Headless variants of the five base profiles for automation use (propose, reflect, tasks).
+ *
+ * These profiles use `stdio: "captured"` and `parseOutput: "json"` so the
+ * agent's response can be read from stdout. They share the same `bin` and
+ * `envPassthrough` as the corresponding base profile but are intentionally
+ * kept out of `BUILTIN_AGENT_PROFILE_NAMES` (and therefore out of CLI
+ * detection/enumeration) to avoid showing up as separate installable profiles.
+ *
+ * Users may reference them by name via `--profile opencode-headless` or by
+ * setting `agent.default: "opencode-headless"` in config.json.
+ */
+const HEADLESS_BUILTINS = {
+    "opencode-headless": {
+        name: "opencode-headless",
+        bin: "opencode",
+        args: ["run"],
+        stdio: "captured",
+        envPassthrough: [...COMMON_PASSTHROUGH, "OPENCODE_API_KEY", "OPENCODE_CONFIG"],
+        parseOutput: "json",
+    },
+    "claude-headless": {
+        name: "claude-headless",
+        bin: "claude",
+        args: [],
+        stdio: "captured",
+        envPassthrough: [...COMMON_PASSTHROUGH, "ANTHROPIC_API_KEY", "CLAUDE_CONFIG"],
+        parseOutput: "json",
+    },
+    "codex-headless": {
+        name: "codex-headless",
+        bin: "codex",
+        args: [],
+        stdio: "captured",
+        envPassthrough: [...COMMON_PASSTHROUGH, "OPENAI_API_KEY", "CODEX_CONFIG"],
+        parseOutput: "json",
+    },
+    "gemini-headless": {
+        name: "gemini-headless",
+        bin: "gemini",
+        args: [],
+        stdio: "captured",
+        envPassthrough: [...COMMON_PASSTHROUGH, "GEMINI_API_KEY", "GOOGLE_API_KEY"],
+        parseOutput: "json",
+    },
+    "aider-headless": {
+        name: "aider-headless",
+        bin: "aider",
+        args: ["--no-auto-commits"],
+        stdio: "captured",
+        envPassthrough: [...COMMON_PASSTHROUGH, "OPENAI_API_KEY", "ANTHROPIC_API_KEY"],
+        parseOutput: "json",
+    },
+};
+/**
+ * Names of the five primary built-in profiles. Stable, sorted. Does NOT
+ * include the `-headless` variants (those are resolvable by name but are
+ * excluded from detection/enumeration flows).
+ */
 export const BUILTIN_AGENT_PROFILE_NAMES = Object.freeze(Object.keys(BUILTINS).sort());
-/** Returns the built-in profile by name, or `undefined` if not built-in. */
+/** Returns the built-in profile by name (including headless variants), or `undefined` if not found. */
 export function getBuiltinAgentProfile(name) {
-    return BUILTINS[name];
+    return BUILTINS[name] ?? HEADLESS_BUILTINS[name];
 }
 /**
- * Return a deep copy of every built-in profile keyed by name. Callers
- * should not assume reference equality with subsequent calls.
+ * Return a deep copy of every primary built-in profile keyed by name.
+ * Headless variants are NOT included — use `getBuiltinAgentProfile(name)`
+ * to look them up by name. Callers should not assume reference equality with
+ * subsequent calls.
  */
 export function listBuiltinAgentProfiles() {
     const out = {};

package/dist/integrations/agent/prompts.js

@@ -23,13 +23,14 @@
  * during validation. We carry it through if the agent supplies it.
  */
 import { TYPE_DIRS } from "../../core/asset-spec";
+import { parseEmbeddedJsonResponse, stripCodeFences, stripThinkBlocks } from "../../core/parse";
 /**
  * Per-asset-type frontmatter / authoring hints surfaced in the prompt so
  * the agent can produce content that passes proposal validation. Kept tiny:
  * full schema docs live in `docs/` — these are nudges, not contracts.
  */
 const TYPE_HINTS = {
-    lesson: "lesson assets MUST start with frontmatter containing `description` and `when_to_use` keys (both non-empty). Body should be 1–3 short paragraphs of practical guidance.",
+    lesson: "lesson assets MUST start with frontmatter containing `description` and `when_to_use` keys (both non-empty). Body: 1–3 short paragraphs of practical guidance. A lesson is NOT a restatement of the source asset — it answers: When should I reach for this? What goes wrong without it? What did real use reveal that the asset itself doesn't say?",
     skill: "skill assets are stored as `skills/<name>/SKILL.md`. Frontmatter typically includes `name`, `description`, and `when_to_use`.",
     command: "command assets are markdown with optional frontmatter (`name`, `description`). The body is the prompt template the user invokes.",
     agent: "agent assets are markdown with frontmatter describing the agent role (`name`, `description`, optional `tools`, `model`).",
@@ -47,16 +48,30 @@ function knownTypeList() {
     return Object.keys(TYPE_DIRS).sort().join(", ");
 }
 /**
- * Common envelope every prompt asks the agent to honour. The wrapper code
- * uses `JSON.parse(stdout)` to extract the payload — anything outside the
- * JSON object will be treated as a parse error.
+ * Common envelope every prompt asks the agent to honour when NO draft file
+ * path is available. The wrapper code uses `JSON.parse(stdout)` to extract
+ * the payload — anything outside the JSON object will be treated as a parse
+ * error.
  */
-const RESPONSE_CONTRACT = [
+const RESPONSE_CONTRACT_JSON = [
     "Respond ONLY with a single JSON object. No prose before or after.",
     'Shape: {"ref": "<type>:<name>", "content": "<full file contents>", "frontmatter": {...}}',
     "`content` is the full file body that will be written if accepted.",
     "`frontmatter` is optional — include it if `content` starts with `---` so reviewers can sanity-check the keys.",
 ].join("\n");
+/**
+ * Response contract used when a draft file path is available. Instructs the
+ * agent to write the improved asset content directly to the file using its
+ * native file-editing tools — no stdout JSON parsing required.
+ */
+function fileWriteContract(draftFilePath) {
+    return [
+        `Write the complete improved asset content to: ${draftFilePath}`,
+        "Use your file-editing tools to create or overwrite that file.",
+        "Do NOT output JSON to stdout. Do NOT print the file contents. Just write the file.",
+        "When you are done writing the file, output a single line: DRAFT_WRITTEN",
+    ].join("\n");
+}
 /**
  * Build the prompt for `akm reflect [ref]`. Asks the agent to review an
  * existing asset (plus any negative feedback / lint findings) and propose
@@ -66,7 +81,15 @@ const RESPONSE_CONTRACT = [
 export function buildReflectPrompt(input) {
     const sections = [];
     if (input.ref && input.type && input.name) {
-        sections.push(`You are reviewing an akm stash asset (${input.type}) called "${input.name}" and proposing an improved version.`);
+        // Change 2 — type-conditioned goal framing
+        const isLesson = input.type === "lesson";
+        const isSkill = input.type === "skill";
+        const goalSentence = isLesson
+            ? `Your task is to distill what usage signals reveal about this ${input.type} asset — when to reach for it, what goes wrong without it, and what real use has revealed that the asset itself does not say. Do not reproduce the source content; your proposal must add information the source does not contain.`
+            : isSkill
+                ? "Your task is to review this skill asset, identify what the feedback and related distilled lessons show is broken, missing, unclear, or durable enough to promote into long-term documentation, and produce a single improved proposal. If the strongest evidence points to companion reference material rather than the main SKILL.md, you may instead propose a skill-adjacent knowledge doc such as `knowledge:skills/<skill>/references/<topic>`."
+                : `Your task is to review this ${input.type} asset, identify what the feedback signals as broken, missing, or unclear, and produce an improved version. Do not reproduce the source content unchanged; your proposal must correct or add something the source lacks.`;
+        sections.push(goalSentence);
         sections.push(`Target ref: ${input.ref}`);
         sections.push(`Asset-type guidance: ${hintForType(input.type)}`);
     }
@@ -78,6 +101,23 @@ export function buildReflectPrompt(input) {
     if (input.task?.trim()) {
         sections.push(`Task / focus: ${input.task.trim()}`);
     }
+    // Change 3 & 4 — feedback moved before asset content; missing else branch added
+    if (input.feedback && input.feedback.length > 0) {
+        sections.push("Recent feedback / signals:");
+        for (const line of input.feedback)
+            sections.push(`- ${line}`);
+    }
+    else if (!input.ref) {
+        sections.push("Recent feedback / signals:");
+        sections.push("- (no feedback events recorded)");
+    }
+    else if (input.type === "skill" && input.relatedLessons && input.relatedLessons.length > 0) {
+        sections.push("No direct feedback events were recorded. Limit substantive changes to what is justified by the related distilled lessons below; do not speculate beyond that evidence.");
+    }
+    else {
+        // 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.assetContent?.trim()) {
         sections.push("Current asset content (verbatim):");
         sections.push("```");
@@ -90,22 +130,28 @@ export function buildReflectPrompt(input) {
     else {
         sections.push("(No existing asset content was supplied.)");
     }
-    if (input.feedback && input.feedback.length > 0) {
-        sections.push("Recent feedback / signals:");
-        for (const line of input.feedback)
-            sections.push(`- ${line}`);
-    }
-    else if (!input.ref) {
-        sections.push("Recent feedback / signals:");
-        sections.push("- (no feedback events recorded)");
-    }
     if (input.schemaHints && input.schemaHints.length > 0) {
         sections.push("Schema / lint hints to address:");
         for (const line of input.schemaHints)
             sections.push(`- ${line}`);
     }
-    sections.push("Produce a single proposal that addresses the feedback and respects the asset-type contract.");
-    sections.push(RESPONSE_CONTRACT);
+    if (input.relatedLessons && input.relatedLessons.length > 0) {
+        sections.push("Related distilled lessons to evaluate for consolidation:");
+        for (const lesson of input.relatedLessons) {
+            sections.push(`Lesson ref: ${lesson.ref}`);
+            sections.push("```");
+            sections.push(lesson.content.trimEnd());
+            sections.push("```");
+        }
+        sections.push("Evaluate whether these lessons contain strong evidence of factual, repeatable guidance that should be promoted into long-term skill documentation.");
+        sections.push("Promote only guidance that is durable, generally applicable, and supported by repeated evidence. Do not copy anecdotal details, one-off incidents, or duplicate wording verbatim.");
+        sections.push("If the guidance belongs in the main skill instructions, update the skill proposal. If it belongs in a companion reference document, return a `knowledge:skills/<skill>/references/<topic>` proposal instead.");
+    }
+    if (input.avoidPatterns && input.avoidPatterns.length > 0) {
+        sections.push(`## Avoid These Patterns\nPrevious assets in this run produced these errors — do not repeat them:\n${input.avoidPatterns.map((e) => `- ${e}`).join("\n")}`);
+    }
+    sections.push("Produce a single proposal that addresses the feedback and respects the asset-type contract. If the proposal's frontmatter is missing `when_to_use`, you MUST generate one — a one-line trigger sentence describing exactly when a user should reach for this asset.");
+    sections.push(input.draftFilePath ? fileWriteContract(input.draftFilePath) : RESPONSE_CONTRACT_JSON);
     return sections.join("\n\n");
 }
 /**
@@ -124,19 +170,63 @@ export function buildProposePrompt(input) {
             sections.push(`- ${line}`);
     }
     sections.push("Produce a single proposal that, if accepted, would land as the asset described above.");
-    sections.push(RESPONSE_CONTRACT);
+    sections.push(input.draftFilePath ? fileWriteContract(input.draftFilePath) : RESPONSE_CONTRACT_JSON);
+    return sections.join("\n\n");
+}
+/**
+ * Build the prompt for the schema repair pass in `akm improve`. Asks the
+ * agent to add the minimal required frontmatter to an asset that failed
+ * validation — without rewriting the body.
+ */
+export function buildSchemaRepairPrompt(input) {
+    const sections = [];
+    sections.push(`This ${input.type} asset failed schema validation with the error: "${input.reason}". ` +
+        `Your task is to fix the schema issue by adding or correcting the missing/invalid field(s) ` +
+        `while preserving all existing content.`);
+    sections.push(`Target ref: ${input.ref}`);
+    sections.push(`Schema requirements for ${input.type} assets: ${hintForType(input.type)}`);
+    const CONTENT_CAP = 3000;
+    const body = input.assetContent.trimEnd();
+    const truncated = body.length > CONTENT_CAP;
+    sections.push("Current asset content (first 3000 chars — sufficient to generate missing frontmatter):");
+    sections.push("```");
+    sections.push(truncated ? `${body.slice(0, CONTENT_CAP)}\n... [truncated]` : body);
+    sections.push("```");
+    sections.push("Produce the minimal fix: add ONLY the missing required frontmatter field(s). " +
+        "Do not rewrite the body unless it is empty. " +
+        "If `description` is missing, generate a concise one-sentence description from the content. " +
+        "If `when_to_use` is missing, generate a one-line trigger sentence. " +
+        "Preserve all existing frontmatter keys and the full body verbatim.");
+    sections.push(input.draftFilePath ? fileWriteContract(input.draftFilePath) : RESPONSE_CONTRACT_JSON);
     return sections.join("\n\n");
 }
 /**
  * Parse agent stdout into a proposal payload. The agent contract requires a
  * single JSON object; anything else is reported as a parse error so callers
  * can map to {@link AgentFailureReason} `parse_error`.
+ *
+ * Resilient to two common local-LLM failure modes:
+ *  1. `<think>…</think>` blocks emitted before the JSON (stripped by `stripJsonFences`).
+ *  2. Prose preamble / postamble around the JSON object (handled by `extractEmbeddedJson`).
  */
 export function parseAgentProposalPayload(stdout) {
-    const trimmed = stripJsonFences(stdout).trim();
+    // Strip <think> blocks and fences, then attempt full parse with embedded fallback.
+    const trimmed = stripCodeFences(stripThinkBlocks(stdout)).trim();
     if (!trimmed)
         throw new Error("agent produced empty output");
-    const parsed = JSON.parse(trimmed);
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch (directErr) {
+        // Agent output contains prose before/after the JSON object (e.g. a local
+        // LLM that narrates before responding). Try extracting the first balanced
+        // top-level `{…}` from the text rather than failing immediately.
+        const embedded = parseEmbeddedJsonResponse(trimmed);
+        if (!embedded)
+            throw directErr;
+        parsed = embedded;
+    }
     if (typeof parsed.ref !== "string" || !parsed.ref.trim()) {
         throw new Error('agent response missing required string field "ref"');
     }
@@ -153,15 +243,10 @@ export function parseAgentProposalPayload(stdout) {
     return out;
 }
 /**
- * Strip `\`\`\`json … \`\`\`` fences if the agent wrapped its JSON output.
- * Mirrors the same helper in `src/llm/client.ts` but kept local here so
- * `agent/` does not import from `llm/` (the boundary is one-way per
- * v1 spec §9.7 — agents are shell-out only).
+ * 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) {
-    const trimmed = text.trim();
-    const fenced = trimmed.match(/^```(?:json)?\s*\n([\s\S]*?)\n```$/);
-    if (fenced)
-        return fenced[1] ?? trimmed;
-    return trimmed;
+    return stripCodeFences(stripThinkBlocks(text));
 }