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

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

@@ -11,6 +11,15 @@
  *               always resolve to the full name for determinism)
  */
 const BUILTIN_ALIASES = [
+    {
+        // Anthropic's Mythos-class tier above Opus — the recommended resolution
+        // target for the `deep` workflow tier (see docs/features/workflows.md).
+        alias: "fable",
+        platforms: {
+            claude: "claude-fable-5",
+            opencode: "opencode/claude-fable-5",
+        },
+    },
     {
         alias: "opus",
         platforms: {
@@ -39,13 +48,18 @@ const BUILTIN_ALIASES = [
  *
  * @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.
+ * @param custom  Profile-level aliases from config.json — take priority over globals and builtins.
+ * @param global  Config-root `modelAliases` tier table (alias → platform → model, `"*"` fallback).
  * @returns Resolved model string, or `model` verbatim when no alias matches.
  */
-export function resolveModel(model, platform, custom) {
+export function resolveModel(model, platform, custom, global) {
     const key = model.toLowerCase();
     if (custom?.[key])
         return custom[key];
+    const tier = global?.[key];
+    const fromGlobal = tier?.[platform] ?? tier?.["*"];
+    if (fromGlobal)
+        return fromGlobal;
     const entry = BUILTIN_ALIASES.find((a) => a.alias === key);
     return entry?.platforms[platform] ?? model;
 }

package/dist/integrations/agent/profiles.js

@@ -1,11 +1,18 @@
 // 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/.
-const COMMON_PASSTHROUGH = ["HOME", "PATH", "USER", "LANG", "LC_ALL", "TERM", "TMPDIR"];
+// AKM_EVENT_SOURCE carries usage-event provenance (improve/task) so that akm
+// invocations a spawned agent makes are recorded as machine traffic, not user
+// demand (DRIFT-6). Without it in the passthrough whitelist, buildChildEnv drops
+// the stamp at the agent boundary — e.g. `akm wiki ingest` spawns an agent whose
+// `akm curate/show/search` tool-calls then log source='user', silently inflating
+// every lane's read-back (GRR). It is a provenance tag, never a secret.
+const COMMON_PASSTHROUGH = ["HOME", "PATH", "USER", "LANG", "LC_ALL", "TERM", "TMPDIR", "AKM_EVENT_SOURCE"];
 /**
- * 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.
+ * Built-in profiles for the agent CLIs akm knows out of the box: the five the
+ * v1 spec calls out explicitly, plus the P2 harness adapters (copilot, pi,
+ * amazonq, openhands — plan §"Capability matrix"). The fields here are
+ * conservative defaults — every value is overridable from user config.
  *
  * For headless/automation use (propose, reflect, tasks), use the '-headless' variant.
  */
@@ -50,9 +57,42 @@ const BUILTINS = {
         envPassthrough: [...COMMON_PASSTHROUGH, "OPENAI_API_KEY", "ANTHROPIC_API_KEY"],
         parseOutput: "text",
     },
+    // ── P2 harness-adapter profiles (plan §"Capability matrix") ────────────────
+    copilot: {
+        name: "copilot",
+        bin: "copilot",
+        args: [],
+        stdio: "interactive",
+        envPassthrough: [...COMMON_PASSTHROUGH, "GH_TOKEN", "GITHUB_TOKEN"],
+        parseOutput: "text",
+    },
+    pi: {
+        name: "pi",
+        bin: "pi",
+        args: [],
+        stdio: "interactive",
+        envPassthrough: [...COMMON_PASSTHROUGH, "PI_API_KEY", "ANTHROPIC_API_KEY", "OPENAI_API_KEY"],
+        parseOutput: "text",
+    },
+    amazonq: {
+        name: "amazonq",
+        bin: "q",
+        args: [],
+        stdio: "interactive",
+        envPassthrough: [...COMMON_PASSTHROUGH, "AWS_PROFILE", "AWS_REGION"],
+        parseOutput: "text",
+    },
+    openhands: {
+        name: "openhands",
+        bin: "openhands",
+        args: [],
+        stdio: "interactive",
+        envPassthrough: [...COMMON_PASSTHROUGH, "LLM_MODEL", "LLM_API_KEY", "LLM_BASE_URL"],
+        parseOutput: "text",
+    },
 };
 /**
- * Headless variants of the five base profiles for automation use (propose, reflect, tasks).
+ * Headless variants of the 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
@@ -104,9 +144,42 @@ const HEADLESS_BUILTINS = {
         envPassthrough: [...COMMON_PASSTHROUGH, "OPENAI_API_KEY", "ANTHROPIC_API_KEY"],
         parseOutput: "json",
     },
+    // ── P2 harness-adapter headless variants (plan §"Capability matrix") ───────
+    "copilot-headless": {
+        name: "copilot-headless",
+        bin: "copilot",
+        args: [],
+        stdio: "captured",
+        envPassthrough: [...COMMON_PASSTHROUGH, "GH_TOKEN", "GITHUB_TOKEN"],
+        parseOutput: "json",
+    },
+    "pi-headless": {
+        name: "pi-headless",
+        bin: "pi",
+        args: [],
+        stdio: "captured",
+        envPassthrough: [...COMMON_PASSTHROUGH, "PI_API_KEY", "ANTHROPIC_API_KEY", "OPENAI_API_KEY"],
+        parseOutput: "json",
+    },
+    "amazonq-headless": {
+        name: "amazonq-headless",
+        bin: "q",
+        args: [],
+        stdio: "captured",
+        envPassthrough: [...COMMON_PASSTHROUGH, "AWS_PROFILE", "AWS_REGION"],
+        parseOutput: "json",
+    },
+    "openhands-headless": {
+        name: "openhands-headless",
+        bin: "openhands",
+        args: [],
+        stdio: "captured",
+        envPassthrough: [...COMMON_PASSTHROUGH, "LLM_MODEL", "LLM_API_KEY", "LLM_BASE_URL"],
+        parseOutput: "json",
+    },
 };
 /**
- * Names of the five primary built-in profiles. Stable, sorted. Does NOT
+ * Names of the primary built-in profiles. Stable, sorted. Does NOT
  * include the `-headless` variants (those are resolvable by name but are
  * excluded from detection/enumeration flows).
  */

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,83 @@
+// 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 { closeServer as disposeOpencodeSdkServers, runOpencodeSdk } from "../harnesses/opencode-sdk/index.js";
+import { runAgent } from "./spawn.js";
+/**
+ * Release every long-lived resource the dispatch runners CACHE for reuse, so a
+ * one-shot process (the CLI) can exit cleanly once dispatching is done.
+ *
+ * The `sdk` runner keeps a per-env registry of `opencode serve` CHILD
+ * PROCESSES (see `opencode-sdk/sdk-runner.ts`), started lazily and reused
+ * across units within a process. Each live child is an OS handle that keeps
+ * Bun's event loop open — and the registry's own teardown is wired ONLY to
+ * `process.once('exit')`, which never fires while such a child holds the loop
+ * open. That is a deadlock: a successful `akm workflow run` that dispatched via
+ * the SDK path would hang the CLI (owner finding 4) because the process is
+ * never idle enough for the exit hook to run and close the children it is
+ * waiting on.
+ *
+ * The engine therefore calls this in its run `finally` (every exit path —
+ * success, gate rejection, failure, abort) to drain the registry deterministically
+ * BEFORE relying on the event loop to drain. The close is synchronous and
+ * idempotent; when no SDK server was ever started it is a no-op, so the `agent`
+ * / `llm` dispatch paths pay nothing. Servers are re-created lazily on the next
+ * dispatch, so calling this between independent dispatch invocations is safe.
+ */
+export function disposeDispatchResources() {
+    disposeOpencodeSdkServers();
+}
+/**
+ * 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";