akm-cli 0.6.0 → 0.7.0-rc1

package/dist/{indexer → src/indexer}/metadata.js

@@ -3,10 +3,49 @@ import path from "node:path";
 import { deriveCanonicalAssetName, deriveCanonicalAssetNameFromStashRoot, isRelevantAssetFile, } from "../core/asset-spec";
 import { isAssetType } from "../core/common";
 import { parseFrontmatter, toStringOrUndefined } from "../core/frontmatter";
-import { warn } from "../core/warn";
+import { isVerbose, warn } from "../core/warn";
 import { buildFileContext, buildRenderContext, getRenderer, runMatchers } from "./file-context";
+export const SCOPE_KEYS = ["user", "agent", "run", "channel"];
 // ── Load / Write ────────────────────────────────────────────────────────────
 const STASH_FILENAME = ".stash.json";
+// ── Quality semantics (v1 spec §4.2) ────────────────────────────────────────
+/**
+ * Well-known quality values. `generated` and `curated` are included in
+ * default search; `proposed` is excluded by default and opt-in via
+ * `--include-proposed`. Unknown values warn once and remain searchable.
+ */
+export const KNOWN_QUALITY_VALUES = new Set(["generated", "curated", "proposed"]);
+/** Tracks unknown quality values we've already warned about (one warn per value per process). */
+const warnedUnknownQualityValues = new Set();
+/**
+ * Normalize a `quality` string off a stash entry. Known values pass through
+ * untouched. Unknown values are accepted as-is (preserved verbatim on the
+ * entry) but trigger a one-time warning per unique value via the shared
+ * `warn()` helper (honours --quiet / `setQuiet()`).
+ */
+export function normalizeQuality(raw) {
+    if (KNOWN_QUALITY_VALUES.has(raw))
+        return raw;
+    if (!warnedUnknownQualityValues.has(raw)) {
+        warnedUnknownQualityValues.add(raw);
+        warn(`Warning: unknown quality value "${raw}" — entry remains searchable, but consider using "generated", "curated", or "proposed" (v1 spec §4.2).`);
+    }
+    return raw;
+}
+/**
+ * Test-only: clear the per-process unknown-quality warning memo so a test
+ * can re-trigger the warning. Not part of the public API.
+ */
+export function _resetUnknownQualityWarnings() {
+    warnedUnknownQualityValues.clear();
+}
+/**
+ * Returns true if an entry's quality marks it as "proposed". Proposed
+ * entries are excluded from default search per v1 spec §4.2.
+ */
+export function isProposedQuality(quality) {
+    return quality === "proposed";
+}
 export function stashFilePath(dirPath) {
     return path.join(dirPath, STASH_FILENAME);
 }
@@ -97,8 +136,9 @@ export function validateStashEntry(entry) {
     }
     if (typeof e.filename === "string" && e.filename)
         result.filename = e.filename;
-    if (e.quality === "generated" || e.quality === "curated")
-        result.quality = e.quality;
+    if (typeof e.quality === "string" && e.quality.length > 0) {
+        result.quality = normalizeQuality(e.quality);
+    }
     if (typeof e.confidence === "number" && Number.isFinite(e.confidence))
         result.confidence = Math.max(0, Math.min(1, e.confidence));
     if (typeof e.source === "string" &&
@@ -157,6 +197,11 @@ export function validateStashEntry(entry) {
         if (filtered.length > 0)
             result.sources = filtered;
     }
+    if (typeof e.scope === "object" && e.scope !== null && !Array.isArray(e.scope)) {
+        const scope = normalizeScopeObject(e.scope);
+        if (scope)
+            result.scope = scope;
+    }
     if (Array.isArray(e.parameters)) {
         const validated = e.parameters
             .filter((p) => {
@@ -183,6 +228,46 @@ export function validateStashEntry(entry) {
     }
     return result;
 }
+/**
+ * Coerce a raw `{ user, agent, run, channel }` object into a clean
+ * `StashEntryScope`, dropping non-string and empty values. Returns
+ * `undefined` when no recognized keys carry a value.
+ */
+function normalizeScopeObject(raw) {
+    const out = {};
+    for (const key of SCOPE_KEYS) {
+        const value = raw[key];
+        if (typeof value === "string") {
+            const trimmed = value.trim();
+            if (trimmed)
+                out[key] = trimmed;
+        }
+        else if (typeof value === "number" && Number.isFinite(value)) {
+            out[key] = String(value);
+        }
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/**
+ * Pull `scope_user` / `scope_agent` / `scope_run` / `scope_channel` out of
+ * a parsed frontmatter block and attach them as `entry.scope`. Tolerates
+ * missing or malformed values; legacy memories without these keys are left
+ * untouched (no `scope` field added).
+ */
+export function applyScopeFrontmatter(entry, fmData) {
+    const collected = {};
+    for (const key of SCOPE_KEYS) {
+        const fmKey = `scope_${key}`;
+        if (Object.hasOwn(fmData, fmKey)) {
+            collected[key] = fmData[fmKey];
+        }
+    }
+    if (Object.keys(collected).length === 0)
+        return;
+    const scope = normalizeScopeObject(collected);
+    if (scope)
+        entry.scope = scope;
+}
 function normalizeNonEmptyStringList(value) {
     if (typeof value === "string") {
         const trimmed = value.trim();
@@ -255,10 +340,9 @@ const WIKI_INFRA_FILES = new Set(["schema.md", "index.md", "log.md"]);
  * Apply wiki-specific index exclusions while leaving all other stash files
  * untouched.
  *
- * - In a normal stash, excludes `wikis/<name>/raw/**` and wiki-root
- *   `schema.md`, `index.md`, `log.md`.
- * - In a wiki-root stash source (`wikiName`), excludes `raw/**` and those same
- *   root-level infrastructure files.
+ * - In a normal stash, excludes wiki-root `schema.md`, `index.md`, `log.md`.
+ * - In a wiki-root stash source (`wikiName`), excludes those same root-level
+ *   infrastructure files.
  */
 export function shouldIndexStashFile(stashRoot, file, options) {
     const relPath = path.relative(stashRoot, file);
@@ -268,8 +352,6 @@ export function shouldIndexStashFile(stashRoot, file, options) {
     if (segments.length === 0)
         return true;
     if (options?.treatStashRootAsWikiRoot) {
-        if (segments[0] === "raw")
-            return false;
         return !(segments.length === 1 && WIKI_INFRA_FILES.has(segments[0]));
     }
     const wikisIdx = segments.indexOf("wikis");
@@ -278,8 +360,6 @@ export function shouldIndexStashFile(stashRoot, file, options) {
     const wikiRelativeSegments = segments.slice(wikisIdx + 2);
     if (wikiRelativeSegments.length === 0)
         return true;
-    if (wikiRelativeSegments[0] === "raw")
-        return false;
     return !(wikiRelativeSegments.length === 1 && WIKI_INFRA_FILES.has(wikiRelativeSegments[0]));
 }
 /**
@@ -405,6 +485,8 @@ export async function generateMetadata(dirPath, assetType, files, typeRoot = dir
                 entry.parameters = fmParams;
             // Pass wiki-pattern frontmatter through onto the entry
             applyWikiFrontmatter(entry, parsed.data);
+            // Pass canonical scope_* frontmatter through onto the entry
+            applyScopeFrontmatter(entry, parsed.data);
             // Extract parameters from template placeholders ($1, $ARGUMENTS, {{named}})
             if (entry.type === "command") {
                 const cmdParams = extractCommandParameters(parsed.content);
@@ -521,6 +603,8 @@ export async function generateMetadataFlat(stashRoot, files) {
                 entry.parameters = fmParams;
             // Pass wiki-pattern frontmatter through onto the entry
             applyWikiFrontmatter(entry, parsed.data);
+            // Pass canonical scope_* frontmatter through onto the entry
+            applyScopeFrontmatter(entry, parsed.data);
             // Extract parameters from template placeholders ($1, $ARGUMENTS, {{named}})
             if (entry.type === "command") {
                 const cmdParams = extractCommandParameters(parsed.content);
@@ -573,9 +657,28 @@ function buildMetadataSkipWarning(filePath, assetType, error) {
     const warning = assetType === "workflow"
         ? `Skipped workflow ${filePath}:\n${detail}`
         : `Skipped malformed ${assetType} asset at ${filePath}: ${detail}`;
+    // Workflow validation warnings are noisy on cold-start search against fresh
+    // registry-cloned content (see issue #273). At default verbosity we suppress
+    // the per-spec stderr line and rely on a one-line summary emitted by the
+    // indexer driver after the run completes. The full per-file detail is still
+    // returned in the warnings[] array (and IndexResponse.warnings) for
+    // programmatic consumers, and verbose mode restores the immediate stderr
+    // print so workflow authors keep the rich feedback they expect.
+    if (assetType === "workflow" && !isVerbose()) {
+        return warning;
+    }
     warn(warning);
     return warning;
 }
+/**
+ * Returns true when a metadata-skip warning was produced by the workflow
+ * validator. Used by the indexer driver to count workflow skips for the
+ * default-verbosity summary line. Matches the prefix produced by
+ * `buildMetadataSkipWarning` for `assetType === "workflow"`.
+ */
+export function isWorkflowSkipWarning(warning) {
+    return warning.startsWith("Skipped workflow ");
+}
 function normalizeTerms(values) {
     const normalized = new Set();
     for (const value of values) {

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

@@ -0,0 +1,292 @@
+/**
+ * Parser + resolver for the optional `agent` config block (v1 spec §12).
+ *
+ * The on-disk shape is:
+ *
+ * ```jsonc
+ * {
+ *   "agent": {
+ *     "default": "opencode",
+ *     "timeoutMs": 60000,
+ *     "profiles": {
+ *       "opencode": { "bin": "opencode", "args": ["--non-interactive"], ... }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * Unknown keys at any level under `agent` are warn-and-ignored — this is the
+ * v1 §9.2 contract. Missing `agent` block disables agent commands; callers
+ * should reach for {@link requireAgentConfig} to surface a stable
+ * `ConfigError` with a hint pointing at setup.
+ *
+ * No LLM SDK is imported here. The runtime path is shell-out only (see
+ * `./spawn.ts`).
+ */
+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"]);
+/** Keys recognised on a profile entry. */
+const KNOWN_PROFILE_KEYS = new Set(["bin", "args", "stdio", "env", "envPassthrough", "timeoutMs", "parseOutput"]);
+/**
+ * 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;
+/**
+ * Parse a raw value (typically `rawConfig.agent` from `JSON.parse`) into a
+ * normalised {@link AgentConfig}. Returns `undefined` when the value is not
+ * an object (i.e. the block is absent or malformed at the root level — for
+ * malformed roots we emit a warning).
+ *
+ * Unknown keys (top-level and per-profile) are warn-and-ignore. Type errors
+ * on individual fields are warn-and-ignore so a bad `timeoutMs` does not
+ * break the rest of the block.
+ */
+export function parseAgentConfig(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        warn('[akm] Ignoring "agent" config: expected an object.');
+        return undefined;
+    }
+    const raw = value;
+    const out = {};
+    for (const key of Object.keys(raw)) {
+        if (!KNOWN_AGENT_KEYS.has(key)) {
+            warn(`[akm] Ignoring unknown agent config key: "${key}"`);
+        }
+    }
+    if ("default" in raw) {
+        if (typeof raw.default === "string" && raw.default.trim()) {
+            out.default = raw.default.trim();
+        }
+        else if (raw.default !== undefined) {
+            warn("[akm] Ignoring agent.default: expected a non-empty string.");
+        }
+    }
+    if ("timeoutMs" in raw) {
+        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.timeoutMs: expected a positive integer (milliseconds).");
+        }
+    }
+    if ("profiles" in raw) {
+        const profiles = parseAgentProfilesMap(raw.profiles);
+        if (profiles)
+            out.profiles = profiles;
+    }
+    return out;
+}
+function parseAgentProfilesMap(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        warn("[akm] Ignoring agent.profiles: expected an object.");
+        return undefined;
+    }
+    const out = {};
+    for (const [name, raw] of Object.entries(value)) {
+        const parsed = parseAgentProfileConfig(name, raw);
+        if (parsed)
+            out[name] = parsed;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+function parseAgentProfileConfig(name, value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        warn(`[akm] Ignoring agent.profiles."${name}": expected an object.`);
+        return undefined;
+    }
+    const raw = value;
+    const out = {};
+    for (const key of Object.keys(raw)) {
+        if (!KNOWN_PROFILE_KEYS.has(key)) {
+            warn(`[akm] Ignoring unknown agent.profiles."${name}" key: "${key}"`);
+        }
+    }
+    if (typeof raw.bin === "string" && raw.bin.trim()) {
+        out.bin = raw.bin.trim();
+    }
+    else if (raw.bin !== undefined) {
+        warn(`[akm] Ignoring agent.profiles."${name}".bin: expected a non-empty string.`);
+    }
+    if (Array.isArray(raw.args)) {
+        const args = raw.args.filter((a) => typeof a === "string");
+        if (args.length === raw.args.length) {
+            out.args = args;
+        }
+        else {
+            warn(`[akm] Ignoring non-string entries in agent.profiles."${name}".args.`);
+            if (args.length > 0)
+                out.args = args;
+        }
+    }
+    else if (raw.args !== undefined) {
+        warn(`[akm] Ignoring agent.profiles."${name}".args: expected an array of strings.`);
+    }
+    if (raw.stdio === "captured" || raw.stdio === "interactive") {
+        out.stdio = raw.stdio;
+    }
+    else if (raw.stdio !== undefined) {
+        warn(`[akm] Ignoring agent.profiles."${name}".stdio: expected "captured" or "interactive".`);
+    }
+    if (typeof raw.env === "object" && raw.env !== null && !Array.isArray(raw.env)) {
+        const env = {};
+        for (const [k, v] of Object.entries(raw.env)) {
+            if (typeof v === "string")
+                env[k] = v;
+        }
+        if (Object.keys(env).length > 0)
+            out.env = env;
+    }
+    else if (raw.env !== undefined) {
+        warn(`[akm] Ignoring agent.profiles."${name}".env: expected a string-valued object.`);
+    }
+    if (Array.isArray(raw.envPassthrough)) {
+        const list = raw.envPassthrough.filter((s) => typeof s === "string" && s.length > 0);
+        if (list.length > 0)
+            out.envPassthrough = list;
+    }
+    else if (raw.envPassthrough !== undefined) {
+        warn(`[akm] Ignoring agent.profiles."${name}".envPassthrough: expected an array of strings.`);
+    }
+    if (typeof raw.timeoutMs === "number" &&
+        Number.isFinite(raw.timeoutMs) &&
+        Number.isInteger(raw.timeoutMs) &&
+        raw.timeoutMs > 0) {
+        out.timeoutMs = raw.timeoutMs;
+    }
+    else if (raw.timeoutMs !== undefined) {
+        warn(`[akm] Ignoring agent.profiles."${name}".timeoutMs: expected a positive integer.`);
+    }
+    if (raw.parseOutput === "text" || raw.parseOutput === "json") {
+        out.parseOutput = raw.parseOutput;
+    }
+    else if (raw.parseOutput !== undefined) {
+        warn(`[akm] Ignoring agent.profiles."${name}".parseOutput: expected "text" or "json".`);
+    }
+    return out;
+}
+/**
+ * Merge a user override (from `agent.profiles[<name>]`) on top of the
+ * built-in profile (if any) and return the resolved profile. If `name`
+ * matches no built-in and the user override has no `bin`, returns
+ * `undefined` — the profile is unusable.
+ *
+ * Used at the spawn site, never at config-load time. Keeping merge logic
+ * here means the parser stays a pure shape-checker.
+ */
+export function resolveAgentProfile(name, overrides) {
+    const builtin = getBuiltinAgentProfile(name);
+    if (!builtin && !overrides?.bin)
+        return undefined;
+    const base = builtin ??
+        {
+            name,
+            bin: overrides?.bin ?? name,
+            args: [],
+            stdio: "captured",
+            envPassthrough: [],
+            parseOutput: "text",
+        };
+    if (!overrides)
+        return base;
+    const merged = {
+        name,
+        bin: overrides.bin ?? base.bin,
+        args: overrides.args ?? base.args,
+        stdio: overrides.stdio ?? base.stdio,
+        env: overrides.env ?? base.env,
+        envPassthrough: overrides.envPassthrough
+            ? mergePassthrough(base.envPassthrough, overrides.envPassthrough)
+            : base.envPassthrough,
+        timeoutMs: overrides.timeoutMs ?? base.timeoutMs,
+        parseOutput: overrides.parseOutput ?? base.parseOutput,
+    };
+    return merged;
+}
+function mergePassthrough(base, extra) {
+    const seen = new Set();
+    const out = [];
+    for (const k of [...base, ...extra]) {
+        if (!seen.has(k)) {
+            seen.add(k);
+            out.push(k);
+        }
+    }
+    return out;
+}
+/**
+ * Resolve the runnable profile for `name`, or `undefined` if none is
+ * available (no built-in and no user override with a `bin`).
+ */
+export function resolveProfileFromConfig(name, agent) {
+    return resolveAgentProfile(name, agent?.profiles?.[name]);
+}
+/**
+ * Return the names of every profile available in `agent` config (built-in
+ * names plus any user-defined ones). Sorted, deduplicated.
+ */
+export function listAgentProfileNames(agent) {
+    const seen = new Set(BUILTIN_AGENT_PROFILE_NAMES);
+    for (const name of Object.keys(agent?.profiles ?? {}))
+        seen.add(name);
+    return [...seen].sort();
+}
+/**
+ * Resolve the default profile name. Order: explicit `name` arg → config
+ * `agent.default` → undefined.
+ */
+export function resolveDefaultProfileName(agent, requested) {
+    if (requested?.trim())
+        return requested.trim();
+    if (agent?.default?.trim())
+        return agent.default.trim();
+    return undefined;
+}
+/**
+ * Throw a {@link ConfigError} with a stable hint when the caller needs
+ * `agent` config but it is missing or unresolvable.
+ *
+ * Covers two cases per acceptance criteria:
+ *
+ * 1. The `agent` block is absent — agent commands are disabled.
+ * 2. The block exists but no usable profile (no `default`, no requested
+ *    name, or the named profile cannot be resolved).
+ *
+ * Use as `const profile = requireAgentProfile(config.agent, requestedName)`.
+ */
+export function requireAgentProfile(agent, requested) {
+    if (!agent) {
+        throw new ConfigError("agent commands are disabled: no `agent` block in config.json.", "INVALID_CONFIG_FILE", 'Run `akm setup` to detect and configure an agent CLI, or add an `agent` block manually (see docs/configuration.md "agent.*").');
+    }
+    const name = resolveDefaultProfileName(agent, requested);
+    if (!name) {
+        throw new ConfigError("agent commands require a profile: pass --profile or set `agent.default` in config.json.", "INVALID_CONFIG_FILE", `Available profiles: ${listAgentProfileNames(agent).join(", ")}.`);
+    }
+    const profile = resolveProfileFromConfig(name, agent);
+    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(", ")}.`);
+    }
+    return profile;
+}
+/**
+ * Convenience: list every fully-resolved profile (built-ins merged with
+ * any user overrides). Used by setup detection to enumerate candidates.
+ */
+export function listResolvedAgentProfiles(agent) {
+    const resolved = [];
+    const builtins = listBuiltinAgentProfiles();
+    for (const name of listAgentProfileNames(agent)) {
+        const profile = resolveProfileFromConfig(name, agent) ?? builtins[name];
+        if (profile)
+            resolved.push(profile);
+    }
+    return resolved;
+}

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

@@ -0,0 +1,94 @@
+/**
+ * Setup-time agent CLI detection (v1 spec §12.3).
+ *
+ * Probes every known/configured agent profile by checking `which <bin>` on
+ * PATH. We do **not** call `<bin> --version` — that would execute the
+ * binary at setup time, which is unnecessarily side-effectful for
+ * detection. The presence of the binary on PATH is sufficient signal; the
+ * spawn wrapper handles failures at run-time.
+ *
+ * Tests inject a fake `whichFn` so detection branches can be exercised
+ * without poking at the real PATH.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { listResolvedAgentProfiles } from "./config";
+/**
+ * Default PATH lookup. Walks `process.env.PATH` and returns the first
+ * existing executable file. Returns `undefined` when the bin is not on
+ * PATH or the env is empty.
+ *
+ * `process.env.PATH` is split on the platform-correct delimiter; on
+ * Windows the binary may have an executable extension, but for v1 we
+ * keep this Unix-flavoured (Bun's primary target) and look for an exact
+ * match.
+ */
+export function defaultWhich(bin, envSource = process.env) {
+    if (!bin || bin.includes("/") || bin.includes("\\")) {
+        // Absolute / relative paths: caller already specified location.
+        try {
+            return fs.statSync(bin).isFile() ? bin : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const pathVar = envSource.PATH ?? envSource.Path ?? envSource.path ?? "";
+    if (!pathVar)
+        return undefined;
+    const sep = pathVar.includes(";") && !pathVar.includes(":") ? ";" : path.delimiter;
+    for (const dir of pathVar.split(sep)) {
+        if (!dir)
+            continue;
+        const candidate = path.join(dir, bin);
+        try {
+            const st = fs.statSync(candidate);
+            if (st.isFile())
+                return candidate;
+        }
+        catch {
+            /* keep walking */
+        }
+    }
+    return undefined;
+}
+/**
+ * Probe every resolvable agent profile (built-ins plus user overrides)
+ * for an installed CLI.
+ *
+ * @param agent  Optional `agent` config block. When omitted we probe the
+ *               built-ins.
+ * @param whichFn  Binary lookup. Tests should inject a stub.
+ */
+export function detectAgentCliProfiles(agent, whichFn = defaultWhich) {
+    const profiles = listResolvedAgentProfiles(agent);
+    return profiles.map((profile) => probeProfile(profile, whichFn));
+}
+function probeProfile(profile, whichFn) {
+    const resolved = whichFn(profile.bin);
+    return {
+        name: profile.name,
+        bin: profile.bin,
+        available: Boolean(resolved),
+        ...(resolved ? { resolvedPath: resolved } : {}),
+    };
+}
+/**
+ * Pick the default profile to persist after a setup-time detection run.
+ *
+ * Strategy:
+ *   1. If the user already set `agent.default` and that profile is
+ *      available, keep it (round-trip stability).
+ *   2. Otherwise, pick the first available result in detection order.
+ *   3. If nothing is available, return `undefined` and the caller skips
+ *      writing `agent.default`.
+ */
+export function pickDefaultAgentProfile(results, existingDefault) {
+    if (existingDefault) {
+        const match = results.find((r) => r.name === existingDefault && r.available);
+        if (match)
+            return match.name;
+    }
+    const first = results.find((r) => r.available);
+    return first?.name;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Internal entry point for the `agent` integration. CLI-only project — no
+ * public exports map. Other akm modules import from this barrel for the
+ * sake of grouping imports.
+ *
+ * Surface:
+ *   • Types: AgentProfile, AgentConfig, AgentRunResult, AgentFailureReason.
+ *   • Profiles: getBuiltinAgentProfile, listBuiltinAgentProfiles, BUILTIN_AGENT_PROFILE_NAMES.
+ *   • Config: parseAgentConfig, resolveProfileFromConfig, requireAgentProfile, listResolvedAgentProfiles, listAgentProfileNames.
+ *   • Spawn: runAgent.
+ *   • Detection: detectAgentCliProfiles, pickDefaultAgentProfile, defaultWhich.
+ */
+export { DEFAULT_AGENT_TIMEOUT_MS, listAgentProfileNames, listResolvedAgentProfiles, parseAgentConfig, requireAgentProfile, resolveAgentProfile, resolveDefaultProfileName, resolveProfileFromConfig, } from "./config";
+export { defaultWhich, detectAgentCliProfiles, pickDefaultAgentProfile } from "./detect";
+export { BUILTIN_AGENT_PROFILE_NAMES, getBuiltinAgentProfile, listBuiltinAgentProfiles, } from "./profiles";
+export { buildProposePrompt, buildReflectPrompt, parseAgentProposalPayload, stripJsonFences } from "./prompts";
+export { runAgent } from "./spawn";

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

@@ -0,0 +1,65 @@
+const COMMON_PASSTHROUGH = ["HOME", "PATH", "USER", "LANG", "LC_ALL", "TERM", "TMPDIR"];
+/**
+ * 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.
+ */
+const BUILTINS = {
+    opencode: {
+        name: "opencode",
+        bin: "opencode",
+        args: [],
+        stdio: "interactive",
+        envPassthrough: [...COMMON_PASSTHROUGH, "OPENCODE_API_KEY", "OPENCODE_CONFIG"],
+        parseOutput: "text",
+    },
+    claude: {
+        name: "claude",
+        bin: "claude",
+        args: [],
+        stdio: "interactive",
+        envPassthrough: [...COMMON_PASSTHROUGH, "ANTHROPIC_API_KEY", "CLAUDE_CONFIG"],
+        parseOutput: "text",
+    },
+    codex: {
+        name: "codex",
+        bin: "codex",
+        args: [],
+        stdio: "interactive",
+        envPassthrough: [...COMMON_PASSTHROUGH, "OPENAI_API_KEY", "CODEX_CONFIG"],
+        parseOutput: "text",
+    },
+    gemini: {
+        name: "gemini",
+        bin: "gemini",
+        args: [],
+        stdio: "interactive",
+        envPassthrough: [...COMMON_PASSTHROUGH, "GEMINI_API_KEY", "GOOGLE_API_KEY"],
+        parseOutput: "text",
+    },
+    aider: {
+        name: "aider",
+        bin: "aider",
+        args: ["--no-auto-commits"],
+        stdio: "interactive",
+        envPassthrough: [...COMMON_PASSTHROUGH, "OPENAI_API_KEY", "ANTHROPIC_API_KEY"],
+        parseOutput: "text",
+    },
+};
+/** Names of every built-in profile. Stable, sorted. */
+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. */
+export function getBuiltinAgentProfile(name) {
+    return BUILTINS[name];
+}
+/**
+ * Return a deep copy of every built-in profile keyed by name. Callers
+ * should not assume reference equality with subsequent calls.
+ */
+export function listBuiltinAgentProfiles() {
+    const out = {};
+    for (const [name, profile] of Object.entries(BUILTINS)) {
+        out[name] = { ...profile };
+    }
+    return out;
+}