akm-cli 0.8.0-rc2 → 0.8.1

package/dist/integrations/agent/profiles.js

@@ -1,3 +1,6 @@
+// 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"];
 /**
  * Built-in profiles for the five agent CLIs the v1 spec calls out

package/dist/integrations/agent/prompts.js

@@ -1,3 +1,6 @@
+// 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/.
 /**
  * Shared prompt builders for proposal-producing agent commands (#226).
  *
@@ -38,7 +41,8 @@ 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.",
-    vault: "vault assets store environment variables (KEY=VALUE pairs). Comments use `#`. Never echo secret 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>` (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.",
+    vault: "vault assets are DEPRECATED (use env). They store environment variables (KEY=VALUE pairs); comments use `#`. Never echo secret values back to the user.",
     wiki: "wiki assets are markdown reference pages with `# Title` and structured headings.",
 };
 function hintForType(type) {
@@ -55,9 +59,15 @@ function knownTypeList() {
  */
 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": {...}}',
+    'Shape: {"ref": "<type>:<name>", "content": "<full file contents>", "frontmatter": {...}, "confidence": <number 0..1>}',
     "`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.",
+    "`confidence` is REQUIRED. Self-rate this proposal on [0, 1] by how certain you are it materially improves the source asset. Calibrate honestly:",
+    "  • 0.90+ — high certainty: fixes a real defect or adds load-bearing missing content; a reviewer would clearly accept.",
+    "  • 0.70–0.89 — clear improvement, but a reviewer might reasonably prefer different framing or scope.",
+    "  • 0.50–0.69 — marginal / judgment call; might help, might not be worth the churn.",
+    "  • Below 0.50 — you are not confident this improves on the source. Prefer returning the source body roughly unchanged with a low score over inventing changes.",
+    "Auto-accept gates on confidence ≥ 0.80 by default. Overclaiming ships low-quality changes; underclaiming leaves good ones stuck in queue. Be honest.",
 ].join("\n");
 /**
  * Response contract used when a draft file path is available. Instructs the
@@ -69,14 +79,42 @@ function fileWriteContract(draftFilePath) {
         `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",
+        "When done, output a single line on stdout: DRAFT_WRITTEN confidence=<0.0-1.0>",
+        "`confidence` is REQUIRED and must be your honest self-rated [0, 1] score for this proposal:",
+        "  • 0.90+ — fixes a real defect or adds load-bearing missing content; reviewer would clearly accept.",
+        "  • 0.70–0.89 — clear improvement, but a reviewer might prefer different framing.",
+        "  • 0.50–0.69 — marginal / judgment call.",
+        "  • Below 0.50 — not confident; prefer not writing changes at all.",
+        "Auto-accept gates on confidence ≥ 0.80. Overclaim → low-quality changes land; underclaim → good changes stuck in queue.",
     ].join("\n");
 }
+/**
+ * Extract a confidence score from a `DRAFT_WRITTEN confidence=<n>` line emitted
+ * by an agent following {@link fileWriteContract}. Tolerates trailing prose,
+ * surrounding log lines, and missing/invalid confidence (returns `undefined`
+ * so callers can keep the proposal but skip auto-accept).
+ *
+ * Matched forms (case-insensitive, anywhere in stdout):
+ *   - `DRAFT_WRITTEN confidence=0.85`
+ *   - `DRAFT_WRITTEN confidence=0.85 ...trailing`
+ *   - `DRAFT_WRITTEN` (no confidence — returns `undefined`)
+ */
+export function extractDraftConfidence(stdout) {
+    if (!stdout)
+        return undefined;
+    const match = stdout.match(/\bDRAFT_WRITTEN\b[^\S\r\n]+confidence=([0-9]*\.?[0-9]+)/i);
+    if (!match)
+        return undefined;
+    const value = Number.parseFloat(match[1] ?? "");
+    if (!Number.isFinite(value) || value < 0 || value > 1)
+        return undefined;
+    return value;
+}
 /**
  * Build the prompt for `akm reflect [ref]`. Asks the agent to review an
  * existing asset (plus any negative feedback / lint findings) and propose
- * an improved version. Returns a single string — the agent runtime will
- * forward it as the trailing positional arg.
+ * an improved version. Returns a {@link ReflectPromptResult} containing the
+ * prompt string and an optional character ceiling for max-tokens enforcement.
  */
 export function buildReflectPrompt(input) {
     const sections = [];
@@ -119,9 +157,17 @@ export function buildReflectPrompt(input) {
         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):");
+        // 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,
+        // long runbooks) would otherwise trigger E2BIG on posix_spawn.
+        const REFLECT_CONTENT_CAP = 12_000;
+        const body = input.assetContent.trimEnd();
+        const truncated = body.length > REFLECT_CONTENT_CAP;
+        sections.push(truncated
+            ? `Current asset content (first ${REFLECT_CONTENT_CAP} chars — full asset is ${body.length} chars):`
+            : "Current asset content (verbatim):");
         sections.push("```");
-        sections.push(input.assetContent.trimEnd());
+        sections.push(truncated ? `${body.slice(0, REFLECT_CONTENT_CAP)}\n... [truncated — focus on the visible portion]` : body);
         sections.push("```");
     }
     else if (input.ref) {
@@ -147,12 +193,86 @@ export function buildReflectPrompt(input) {
         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.rejectedProposals && input.rejectedProposals.length > 0) {
+        const lines = ["## Previously Rejected Proposals"];
+        lines.push("The following proposals for this ref were already reviewed and rejected. " +
+            "Do NOT reproduce the same content or the same structural shape. " +
+            "Your new proposal must meaningfully differ from each of these in its approach, framing, or evidence used.");
+        for (const rp of input.rejectedProposals) {
+            lines.push(`\nRef: ${rp.ref}`);
+            lines.push(`Rejection reason: ${rp.reason}`);
+            if (rp.contentPreview) {
+                lines.push("Rejected content preview:");
+                lines.push("```");
+                lines.push(rp.contentPreview);
+                lines.push("```");
+            }
+        }
+        sections.push(lines.join("\n"));
+    }
     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")}`);
     }
+    // R-1 / #372: Self-Refine (arXiv:2303.17651) — inject prior draft as critique target.
+    // On refinement iterations (iter > 0), the agent is shown its previous proposal
+    // and asked to self-critique and improve it rather than starting from scratch.
+    if (input.priorDraft?.trim()) {
+        sections.push("## Self-Refine: Critique and Improve\n" +
+            "The following is your previous draft proposal. " +
+            "Identify specific weaknesses: missing evidence, vague wording, incomplete frontmatter, " +
+            "or claims that duplicate existing content without adding new signal. " +
+            "Then produce an improved version that addresses those weaknesses. " +
+            "The revised proposal must be meaningfully better than the draft below — " +
+            "do not return the same content unchanged.\n\n" +
+            "Previous draft:\n```\n" +
+            input.priorDraft.trimEnd() +
+            "\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.");
+    // Content-preservation safety rails (#reflect-pipeline-fixes).
+    // These rules counter the observed failure modes where reflect rewrites
+    // asset content into shorter prose, drops concrete structure, or strips
+    // load-bearing frontmatter. Loud and explicit so small models follow.
+    //
+    // maxOutputChars is hoisted so the return value can include it for callers
+    // on the LLM path that want to set a hard max_tokens cap on the request.
+    let maxOutputChars;
+    if (input.ref && input.assetContent?.trim()) {
+        // Strip frontmatter to get source body length — mirrors checkReflectSize which
+        // compares body-only lengths. Inline regex avoids importing parseFrontmatter.
+        const rawContent = input.assetContent.trimEnd();
+        const fmBodyMatch = rawContent.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?([\s\S]*)$/);
+        const sourceBodyLen = (fmBodyMatch ? fmBodyMatch[1] : rawContent).trim().length;
+        // Compute concrete char bounds matching checkReflectSize constants:
+        //   REFLECT_SIZE_GUARD_MIN_BYTES=200, REFLECT_SHRINK_RATIO_MIN=0.5,
+        //   REFLECT_ABSOLUTE_FLOOR_BYTES=150, REFLECT_EXPAND_RATIO_MAX=2.5,
+        //   REFLECT_ABSOLUTE_CEILING_BYTES=2500, REFLECT_ABSOLUTE_MAX_BYTES=25000.
+        // Embed concrete counts only when the gate will actually fire (source >= 200 chars).
+        const showCharBounds = sourceBodyLen >= 200;
+        const minChars = Math.max(Math.round(0.5 * sourceBodyLen), 150);
+        const maxChars = Math.min(Math.max(Math.round(2.5 * sourceBodyLen), 2500), 25000);
+        if (showCharBounds)
+            maxOutputChars = maxChars;
+        sections.push([
+            "## Content preservation rules (MUST follow)",
+            "1. PRESERVE ALL concrete content: code blocks, fenced snippets, CLI commands, numbered/bulleted checklists, tables, YAML/JSON examples, file paths, configuration keys, environment variable names, and CSS/HTML selectors. These are load-bearing — do NOT replace them with prose summaries.",
+            "2. PRESERVE the source asset's frontmatter. The post-processor reassembles the final asset from the original frontmatter plus your body. Do NOT emit `---` frontmatter delimiters at the top of `content` — start `content` with the markdown body (e.g. `# Heading` or the first paragraph). If you include frontmatter anyway, identity fields (`name`, `ref`, `id`, `slug`, `type`) will be reset to the original values.",
+            showCharBounds
+                ? `3. DO NOT shrink the asset. Your body must be at least ${minChars} characters (source body is ${sourceBodyLen} chars; floor is 50%). If you genuinely need to remove a major section, explain why in a comment line at the top of the body (e.g. \`<!-- removed obsolete section X because ... -->\`).`
+                : "3. DO NOT shrink the asset dramatically. The improved body must be at least 50% of the source body length. If you genuinely need to remove a major section, explain why in a comment line at the top of the body (e.g. `<!-- removed obsolete section X because ... -->`).",
+            showCharBounds
+                ? `4. DO NOT pad the asset with speculative material. Your body must be at most ${maxChars} characters (source body is ${sourceBodyLen} chars; ceiling is 250%). Do not add invented sections, hypothetical examples, or padding prose.`
+                : "4. DO NOT pad the asset with speculative material. The improved body must be at most 250% of the source body length unless the feedback explicitly requests added sections.",
+            "5. Improve clarity of surrounding prose, fix structural issues, add missing required frontmatter fields. Do NOT rewrite a runbook into an essay.",
+        ].join("\n"));
+    }
+    if (!input.draftFilePath && input.ref) {
+        // Reinforce that the `ref` field is mandatory and must exactly match the target.
+        // Small models frequently omit `ref` from the response JSON, causing parse errors.
+        sections.push(`IMPORTANT: The JSON "ref" field is REQUIRED. It MUST be exactly: "${input.ref}"`);
+    }
     sections.push(input.draftFilePath ? fileWriteContract(input.draftFilePath) : RESPONSE_CONTRACT_JSON);
-    return sections.join("\n\n");
+    return { prompt: sections.join("\n\n"), ...(maxOutputChars !== undefined ? { maxOutputChars } : {}) };
 }
 /**
  * Build the prompt for `akm propose <type> <name> --task ...`. Asks the
@@ -240,6 +360,15 @@ export function parseAgentProposalPayload(stdout) {
     if (parsed.frontmatter && typeof parsed.frontmatter === "object" && !Array.isArray(parsed.frontmatter)) {
         out.frontmatter = parsed.frontmatter;
     }
+    // Phase 6A: extract optional `confidence` (number in [0, 1]). Clamp gently
+    // rather than reject — a model that returns 1.0 or 0 with extra precision
+    // (e.g. 1.0000001) should still surface a usable score. Anything that isn't
+    // a finite number is dropped so downstream `createProposal` can rely on the
+    // shape invariant.
+    if (typeof parsed.confidence === "number" && Number.isFinite(parsed.confidence)) {
+        const clamped = Math.max(0, Math.min(1, parsed.confidence));
+        out.confidence = clamped;
+    }
     return out;
 }
 /**

package/dist/integrations/agent/runner.js

@@ -0,0 +1,208 @@
+// 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/.
+import { ConfigError } from "../../core/errors";
+import { warn } from "../../core/warn";
+function resolveEffectiveMode(entry, profileName, config) {
+    if (entry.mode)
+        return entry.mode;
+    // Infer from profile pool when profile is specified
+    if (profileName) {
+        if (config.profiles?.llm?.[profileName])
+            return "llm";
+        const agentProfile = config.profiles?.agent?.[profileName];
+        if (agentProfile) {
+            return agentProfile.platform === "opencode-sdk" ? "sdk" : "agent";
+        }
+    }
+    // Fall back to defaults
+    if (config.defaults?.llm)
+        return "llm";
+    if (config.defaults?.agent)
+        return "agent";
+    return "llm";
+}
+function resolveProfileName(entry, mode, config) {
+    if (entry.profile)
+        return entry.profile;
+    if (mode === "llm") {
+        const defaultName = config.defaults?.llm;
+        if (defaultName)
+            return defaultName;
+        throw new ConfigError(`No LLM profile configured. Set defaults.llm in config or specify profile in the process entry.`, "LLM_NOT_CONFIGURED", "Run `akm setup` or define a profile under `profiles.llm` and set `defaults.llm`.");
+    }
+    const defaultName = config.defaults?.agent;
+    if (defaultName)
+        return defaultName;
+    throw new ConfigError(`No agent profile configured. Set defaults.agent in config or specify profile in the process entry.`, "INVALID_CONFIG_FILE", "Run `akm setup` to configure an agent profile, or add one under `profiles.agent`.");
+}
+function buildLlmRunnerSpec(profileName, timeoutMs, config) {
+    const profile = config.profiles?.llm?.[profileName];
+    if (!profile) {
+        throw new ConfigError(`LLM profile "${profileName}" not found in profiles.llm.`, "LLM_NOT_CONFIGURED", `Available profiles: ${Object.keys(config.profiles?.llm ?? {}).join(", ") || "none"}. Run \`akm setup\` to configure.`);
+    }
+    return {
+        kind: "llm",
+        connection: profile,
+        ...(typeof timeoutMs === "number" ? { timeoutMs } : {}),
+    };
+}
+function buildAgentRunnerSpec(kind, profileName, timeoutMs, config) {
+    const profileConfig = config.profiles?.agent?.[profileName];
+    if (!profileConfig) {
+        throw new ConfigError(`Agent profile "${profileName}" not found in profiles.agent.`, "INVALID_CONFIG_FILE", `Available profiles: ${Object.keys(config.profiles?.agent ?? {}).join(", ") || "none"}. Run \`akm setup\` to configure.`);
+    }
+    // Validate mode/platform consistency
+    if (kind === "sdk" && profileConfig.platform !== "opencode-sdk") {
+        throw new ConfigError(`Mode "sdk" requires platform "opencode-sdk", but profiles.agent["${profileName}"].platform is "${profileConfig.platform}".`, "INVALID_CONFIG_FILE");
+    }
+    if (kind === "agent" && profileConfig.platform === "opencode-sdk") {
+        throw new ConfigError(`Mode "agent" requires platform "opencode" or "claude", but profiles.agent["${profileName}"].platform is "opencode-sdk".`, "INVALID_CONFIG_FILE");
+    }
+    const agentProfile = {
+        name: profileName,
+        bin: profileConfig.bin ?? profileName,
+        args: profileConfig.args ?? [],
+        stdio: "captured",
+        envPassthrough: [],
+        parseOutput: "text",
+        ...(profileConfig.model ? { model: profileConfig.model } : {}),
+        ...(profileConfig.workspace ? { workspace: profileConfig.workspace } : {}),
+    };
+    return {
+        kind,
+        profile: agentProfile,
+        ...(typeof timeoutMs === "number" ? { timeoutMs } : {}),
+    };
+}
+/**
+ * Resolve the runner used for "validation" passes on the `improve` section
+ * (Advantage D3 / Phase 4B — third model tier).
+ *
+ * Look-up order:
+ *   1. `profiles.improve.default.processes.validation` (preferred — lets users
+ *      wire a lower-cost classifier model for staleness detection, confidence
+ *      scoring, and lesson classification).
+ *   2. `defaults.llm` as a final fallback so callers always get a usable
+ *      runner when any LLM is configured.
+ *
+ * Returns `null` when neither is configured (callers may then skip the
+ * validation pass rather than throwing).
+ */
+/**
+ * Shared resolution path for the `validation` and `triage judgment` tiers,
+ * both of which take a `{ mode?, profile?, timeoutMs? }`-shaped block, attempt
+ * to resolve it via {@link resolveImproveProcessRunnerFromProfile}, and
+ * otherwise fall back to an `llm` runner built from `defaults.llm`.
+ *
+ * @param block          the `{ mode?, profile?, timeoutMs? }` subset to resolve.
+ * @param config         the active AKM config.
+ * @param opts.fallbackTimeoutMs  timeout applied to the `defaults.llm` fallback
+ *        runner (validation passes `undefined`; triage forwards `block.timeoutMs`).
+ * @param opts.suppressLlmFallbackForExplicitMode  when `true` and the block
+ *        explicitly sets `mode: "agent"` or `"sdk"`, do NOT silently fall back
+ *        to `defaults.llm` if the profile resolver returns `null` or throws —
+ *        return `null` instead and emit a `warn(...)` (see FIX 8). Validation
+ *        passes `false` to preserve its always-fallback behavior.
+ */
+function resolveProcessRunnerWithLlmFallback(block, config, opts) {
+    const explicitNonLlmMode = block?.mode === "agent" || block?.mode === "sdk";
+    if (block && (block.mode || block.profile)) {
+        try {
+            const spec = resolveImproveProcessRunnerFromProfile(block, config);
+            if (spec)
+                return spec;
+        }
+        catch {
+            // Fall through to defaults.llm below (unless suppressed for explicit modes).
+        }
+        // FIX 8: an EXPLICIT agent/sdk request must not be silently downgraded to
+        // llm. When the profile resolver could not produce a runner, surface the
+        // misconfiguration and let callers skip this tier rather than substituting
+        // an llm judge.
+        if (opts.suppressLlmFallbackForExplicitMode && explicitNonLlmMode) {
+            warn(`[akm] Could not resolve the "${block?.mode}" judgment profile; ` +
+                `skipping the judgment tier instead of falling back to an llm judge. ` +
+                `Check profiles.agent and the judgment profile/mode configuration.`);
+            return null;
+        }
+    }
+    const defaultLlm = config.defaults?.llm;
+    if (defaultLlm) {
+        try {
+            return buildLlmRunnerSpec(defaultLlm, opts.fallbackTimeoutMs, config);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+export function resolveValidationRunner(config) {
+    const validation = config.profiles?.improve?.default?.processes?.validation;
+    const block = validation && validation.enabled !== false ? validation : undefined;
+    return resolveProcessRunnerWithLlmFallback(block, config, {
+        fallbackTimeoutMs: undefined,
+        suppressLlmFallbackForExplicitMode: false,
+    });
+}
+/**
+ * Resolve the runner for the triage judgment tier (Proposal-Queue Triage,
+ * Phase 3). The `judgment` block is a `{ mode?, profile?, timeoutMs? }` subset
+ * compatible with {@link ImproveProcessConfig}, so it resolves through the same
+ * {@link resolveImproveProcessRunnerFromProfile} path.
+ *
+ * Mirrors {@link resolveValidationRunner}'s `defaults.llm` fallback only for
+ * the unset/`llm` case: when the block sets neither `mode` nor `profile` (so
+ * the profile resolver returns `null`) or `mode: "llm"`, fall back to an `llm`
+ * runner built from `defaults.llm` so `judgment.mode: llm` defaults are honored
+ * (§14). However (FIX 8) when the caller EXPLICITLY sets `mode: "agent"` or
+ * `"sdk"` and the profile resolver returns `null` or throws, do NOT downgrade
+ * to an llm judge — return `null` (callers skip the judgment tier and emit
+ * `triage_deferred`) and emit a `warn(...)`. Returns `null` when nothing is
+ * configured.
+ */
+export function resolveTriageJudgmentRunner(judgment, config) {
+    return resolveProcessRunnerWithLlmFallback(judgment, config, {
+        fallbackTimeoutMs: judgment?.timeoutMs,
+        suppressLlmFallbackForExplicitMode: true,
+    });
+}
+export function resolveRunner(mode, profileName, config) {
+    if (mode === "llm")
+        return buildLlmRunnerSpec(profileName, undefined, config);
+    return buildAgentRunnerSpec(mode, profileName, undefined, config);
+}
+/**
+ * Resolve a RunnerSpec from an improve-profile process entry. Returns `null`
+ * when the entry is absent or provides no overrides — callers should fall
+ * back to the default per-process runner resolution path.
+ */
+export function resolveImproveProcessRunnerFromProfile(processConfig, config) {
+    if (!processConfig)
+        return null;
+    const { mode: explicitMode, profile, timeoutMs } = processConfig;
+    if (!explicitMode && !profile)
+        return null;
+    const mode = explicitMode ?? resolveEffectiveMode(processConfig, profile, config);
+    const profileName = profile ?? resolveProfileName(processConfig, mode, config);
+    if (mode === "llm") {
+        return buildLlmRunnerSpec(profileName, timeoutMs, config);
+    }
+    if (mode === "agent" || mode === "sdk") {
+        return buildAgentRunnerSpec(mode, profileName, timeoutMs, 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";

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

@@ -1,8 +1,12 @@
+// 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/.
 /**
  * OpenCode SDK agent runner — uses embedded @opencode-ai/sdk instead of
  * Bun.spawn. Requires no agent CLI binary to be installed. The user provides
  * an OpenAI-compatible endpoint (or inherits from config.llm) for the SDK.
  */
+import { resolveSecret } from "../../core/config";
 // Singleton server — started once per process, reused across calls
 let _server = null;
 /**
@@ -26,7 +30,7 @@ async function getOrStartServer(profile, llmConfig) {
     });
     // Resolve endpoint and model: profile fields take precedence over config.llm
     const endpoint = profile.endpoint ?? llmConfig?.endpoint;
-    const apiKey = profile.apiKey ?? llmConfig?.apiKey;
+    const apiKey = resolveSecret(profile.apiKey ?? llmConfig?.apiKey);
     const model = profile.model;
     const sdkConfig = {};
     if (model)
@@ -55,7 +59,7 @@ async function getOrStartServer(profile, llmConfig) {
         throw new Error("Failed to initialise OpenCode SDK server.");
     return _server;
 }
-export async function runAgentSdk(profile, prompt, _opts = {}, llmConfig) {
+export async function runOpencodeSdk(profile, prompt, _opts = {}, llmConfig) {
     const start = Date.now();
     let client;
     try {
@@ -118,3 +122,5 @@ export async function runAgentSdk(profile, prompt, _opts = {}, llmConfig) {
         await client.session.delete({ path: { id: sessionId } }).catch(() => { });
     }
 }
+/** @deprecated Use {@link runOpencodeSdk} instead. */
+export const runAgentSdk = runOpencodeSdk;

package/dist/integrations/agent/spawn.js

@@ -1,3 +1,6 @@
+// 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/.
 /**
  * Agent CLI spawn wrapper (v1 spec §12.2).
  *
@@ -14,6 +17,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { getCommandBuilder } from "./builders";
 import { DEFAULT_AGENT_TIMEOUT_MS } from "./config";
 /**
  * Kill the process group of `proc` with `signal`, falling back to
@@ -24,7 +28,7 @@ import { DEFAULT_AGENT_TIMEOUT_MS } from "./config";
  * reaped alongside the node wrapper. The fallback keeps test fakes working
  * without modification.
  */
-export function killGroup(proc, signal) {
+function killGroup(proc, signal) {
     if (typeof proc.pid === "number") {
         try {
             process.kill(-proc.pid, signal);
@@ -61,7 +65,33 @@ export function supplementPathForSchedulerContext(existingPath) {
     if (existingPath.split(path.delimiter).some((d) => d.startsWith(home))) {
         return existingPath;
     }
-    const candidates = [
+    const candidates = pathCandidatesForCurrentPlatform(home);
+    const existing = new Set(existingPath.split(path.delimiter).filter(Boolean));
+    const toAdd = candidates.filter((d) => !existing.has(d) && fs.existsSync(d));
+    if (toAdd.length === 0)
+        return existingPath;
+    return [...toAdd, existingPath].filter(Boolean).join(path.delimiter);
+}
+function pathCandidatesForCurrentPlatform(home) {
+    if (process.platform === "win32") {
+        // Windows: Bun + Cargo + Scoop + Chocolatey + system tools. Order favors
+        // user-local installs over machine-global so the user's chosen toolchain
+        // wins. These paths are commonly stripped from Task Scheduler / service
+        // environments, mirroring the cron/launchd problem on POSIX.
+        const localAppData = process.env.LOCALAPPDATA ?? path.join(home, "AppData", "Local");
+        const userProfile = process.env.USERPROFILE ?? home;
+        const programFiles = process.env.ProgramFiles ?? "C:\\Program Files";
+        return [
+            path.join(userProfile, ".bun", "bin"),
+            path.join(localAppData, "Programs", "bun"),
+            path.join(userProfile, ".cargo", "bin"),
+            path.join(localAppData, "Programs", "Git", "cmd"),
+            path.join(userProfile, "scoop", "shims"),
+            path.join(programFiles, "Git", "cmd"),
+            "C:\\ProgramData\\chocolatey\\bin",
+        ];
+    }
+    return [
         path.join(home, ".bun", "bin"),
         path.join(home, ".cargo", "bin"),
         path.join(home, ".local", "bin"),
@@ -69,11 +99,6 @@ export function supplementPathForSchedulerContext(existingPath) {
         "/opt/homebrew/sbin",
         "/usr/local/bin",
     ];
-    const existing = new Set(existingPath.split(path.delimiter).filter(Boolean));
-    const toAdd = candidates.filter((d) => !existing.has(d) && fs.existsSync(d));
-    if (toAdd.length === 0)
-        return existingPath;
-    return [...toAdd, existingPath].filter(Boolean).join(path.delimiter);
 }
 function resolveSpawnFn(options) {
     if (options.spawn)
@@ -159,15 +184,30 @@ export async function runAgent(profile, prompt, options = {}) {
     const parseOutput = options.parseOutput ?? profile.parseOutput;
     const setTimeoutImpl = options.setTimeoutFn ?? setTimeout;
     const clearTimeoutImpl = options.clearTimeoutFn ?? clearTimeout;
-    const args = [...profile.args, ...(options.args ?? [])];
-    if (prompt !== undefined)
-        args.push(prompt);
-    const env = buildChildEnv(profile, options);
+    // Build argv via the platform-specific builder when dispatch params are
+    // provided; fall back to the legacy positional-prompt form otherwise.
+    let builtArgv;
+    let builtEnv;
+    if (options.dispatch !== undefined) {
+        const builder = getCommandBuilder(profile.commandBuilder ?? profile.name, options.builderRegistry);
+        const built = builder.build(profile, options.dispatch);
+        builtArgv = built.argv;
+        builtEnv = built.env;
+    }
+    else {
+        const legacyArgs = [...profile.args, ...(options.args ?? [])];
+        if (prompt !== undefined)
+            legacyArgs.push(prompt);
+        builtArgv = [profile.bin, ...legacyArgs];
+    }
+    // Extra args (e.g. forwarded CLI positionals) are appended after the builder output.
+    const finalArgv = [...builtArgv, ...(options.dispatch ? (options.args ?? []) : [])];
+    const env = { ...buildChildEnv(profile, options), ...(builtEnv ?? {}) };
     const start = Date.now();
     let proc;
     try {
         const spawnFn = resolveSpawnFn(options);
-        proc = spawnFn([profile.bin, ...args], {
+        proc = spawnFn(finalArgv, {
             stdin: stdioMode === "captured" ? (options.stdin !== undefined ? "pipe" : "ignore") : "inherit",
             stdout: stdioMode === "captured" ? "pipe" : "inherit",
             stderr: stdioMode === "captured" ? "pipe" : "inherit",
@@ -207,13 +247,13 @@ export async function runAgent(profile, prompt, options = {}) {
     let timer;
     if (timeoutMs !== null) {
         timer = setTimeoutImpl(() => {
-            if (proc.exitCode !== null)
+            if (!proc || proc.exitCode !== null)
                 return;
             timedOut = true;
             killGroup(proc, "SIGTERM");
             // Follow up with SIGKILL after 5 s in case the process ignores SIGTERM.
             setTimeoutImpl(() => {
-                if (proc.exitCode !== null)
+                if (!proc || proc.exitCode !== null)
                     return;
                 killGroup(proc, "SIGKILL");
             }, 5000);

package/dist/integrations/github.js

@@ -1,3 +1,6 @@
+// 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/.
 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"]);