akm-cli 0.6.1 → 0.7.0

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

@@ -0,0 +1,167 @@
+/**
+ * Shared prompt builders for proposal-producing agent commands (#226).
+ *
+ * `akm reflect` and `akm propose` both shell out to the configured agent CLI
+ * (via {@link runAgent}) and ask it for a structured proposal payload. The
+ * prompts are intentionally similar — both ask the agent to return a single
+ * JSON object containing `ref`, `content`, and (optionally) `frontmatter` —
+ * so we share the construction here. Keeping the prompt builders in
+ * `src/integrations/agent/` rather than `src/llm/` is deliberate: these are
+ * shell-out prompts targeting an agent CLI, not in-tree LLM API calls.
+ *
+ * The output the agent must produce is a *strict* JSON object:
+ *
+ * ```json
+ * {
+ *   "ref": "lesson:my-lesson",
+ *   "content": "---\ndescription: ...\nwhen_to_use: ...\n---\n\nbody",
+ *   "frontmatter": { "description": "...", "when_to_use": "..." }
+ * }
+ * ```
+ *
+ * `frontmatter` is optional — the proposal queue parses it from `content`
+ * during validation. We carry it through if the agent supplies it.
+ */
+import { TYPE_DIRS } from "../../core/asset-spec";
+/**
+ * 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.",
+    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`).",
+    knowledge: "knowledge assets are reference markdown documents. Include a top-level `# Title` and concise sections.",
+    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.",
+    wiki: "wiki assets are markdown reference pages with `# Title` and structured headings.",
+};
+function hintForType(type) {
+    return TYPE_HINTS[type] ?? `assets of type "${type}" — produce sensible markdown with optional frontmatter.`;
+}
+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.
+ */
+const RESPONSE_CONTRACT = [
+    "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");
+/**
+ * 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.
+ */
+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.`);
+        sections.push(`Target ref: ${input.ref}`);
+        sections.push(`Asset-type guidance: ${hintForType(input.type)}`);
+    }
+    else {
+        sections.push("You are reviewing recent akm feedback and proposing a single improved asset revision.");
+        sections.push("No target ref was supplied. Choose the best target from the feedback below and return it in `ref`.");
+        sections.push(`Known asset types: ${knownTypeList()}.`);
+    }
+    if (input.task?.trim()) {
+        sections.push(`Task / focus: ${input.task.trim()}`);
+    }
+    if (input.assetContent?.trim()) {
+        sections.push("Current asset content (verbatim):");
+        sections.push("```");
+        sections.push(input.assetContent.trimEnd());
+        sections.push("```");
+    }
+    else if (input.ref) {
+        sections.push("(No existing content — propose a fresh asset that fits the ref.)");
+    }
+    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);
+    return sections.join("\n\n");
+}
+/**
+ * Build the prompt for `akm propose <type> <name> --task ...`. Asks the
+ * agent to author a brand-new asset of the given type fulfilling `task`.
+ */
+export function buildProposePrompt(input) {
+    const sections = [];
+    sections.push(`Author a new akm stash asset of type "${input.type}" named "${input.name}".`);
+    sections.push(`Task: ${input.task}`);
+    sections.push(`Asset-type guidance: ${hintForType(input.type)}`);
+    sections.push(`(Known asset types: ${knownTypeList()}.)`);
+    if (input.schemaHints && input.schemaHints.length > 0) {
+        sections.push("Schema / lint hints:");
+        for (const line of input.schemaHints)
+            sections.push(`- ${line}`);
+    }
+    sections.push("Produce a single proposal that, if accepted, would land as the asset described above.");
+    sections.push(RESPONSE_CONTRACT);
+    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`.
+ */
+export function parseAgentProposalPayload(stdout) {
+    const trimmed = stripJsonFences(stdout).trim();
+    if (!trimmed)
+        throw new Error("agent produced empty output");
+    const parsed = JSON.parse(trimmed);
+    if (typeof parsed.ref !== "string" || !parsed.ref.trim()) {
+        throw new Error('agent response missing required string field "ref"');
+    }
+    if (typeof parsed.content !== "string" || !parsed.content.trim()) {
+        throw new Error('agent response missing required string field "content"');
+    }
+    const out = {
+        ref: parsed.ref.trim(),
+        content: parsed.content,
+    };
+    if (parsed.frontmatter && typeof parsed.frontmatter === "object" && !Array.isArray(parsed.frontmatter)) {
+        out.frontmatter = parsed.frontmatter;
+    }
+    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).
+ */
+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;
+}

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

@@ -0,0 +1,272 @@
+/**
+ * Agent CLI spawn wrapper (v1 spec §12.2).
+ *
+ * Single helper that owns:
+ *   • Process spawn (Bun's subprocess API).
+ *   • Captured vs interactive stdio.
+ *   • Hard timeout (per-call override or profile default).
+ *   • Structured failure reasons — `timeout`, `spawn_failed`,
+ *     `non_zero_exit`, `parse_error`.
+ *
+ * NEVER imports an LLM SDK. Agents are reachable only via shell-out;
+ * this is a pre-emptive guarantee against the #222 invariant.
+ */
+import { DEFAULT_AGENT_TIMEOUT_MS } from "./config";
+/**
+ * Kill the process group of `proc` with `signal`, falling back to
+ * `proc.kill(signal)` when `proc.pid` is unavailable (e.g. test fakes).
+ *
+ * Passing a negative PID to `process.kill` targets the entire process
+ * group, so opencode's child processes (the .opencode binary, etc.) are
+ * reaped alongside the node wrapper. The fallback keeps test fakes working
+ * without modification.
+ */
+export function killGroup(proc, signal) {
+    if (typeof proc.pid === "number") {
+        try {
+            process.kill(-proc.pid, signal);
+            return;
+        }
+        catch {
+            // Process may have already exited; fall through to direct kill.
+        }
+    }
+    try {
+        proc.kill(signal);
+    }
+    catch {
+        /* ignore */
+    }
+}
+const DEFAULT_TIMEOUT_MS = DEFAULT_AGENT_TIMEOUT_MS;
+function resolveSpawnFn(options) {
+    if (options.spawn)
+        return options.spawn;
+    // Pull from globalThis so tests that swap it out at module level are honoured.
+    const bun = globalThis.Bun;
+    if (!bun?.spawn) {
+        throw new Error("Bun.spawn is unavailable; pass options.spawn for non-Bun environments.");
+    }
+    return bun.spawn.bind(bun);
+}
+/**
+ * Build the child env. Starts empty and copies through:
+ *   • Every name in `profile.envPassthrough`.
+ *   • Every entry in `profile.env`.
+ *   • Every entry in `options.env` (highest precedence).
+ */
+function buildChildEnv(profile, options) {
+    const source = options.envSource ?? process.env;
+    const env = {};
+    for (const name of profile.envPassthrough) {
+        const value = source[name];
+        if (value !== undefined)
+            env[name] = value;
+    }
+    if (profile.env) {
+        for (const [k, v] of Object.entries(profile.env))
+            env[k] = v;
+    }
+    if (options.env) {
+        for (const [k, v] of Object.entries(options.env))
+            env[k] = v;
+    }
+    return env;
+}
+async function readStream(stream, opts) {
+    if (!stream)
+        return "";
+    const readPromise = new Response(stream).text().catch(() => "");
+    if (!opts?.timeoutMs)
+        return readPromise;
+    // Race the stream read against a timeout so a process that is killed via
+    // SIGTERM/SIGKILL but whose pipe endpoints stay open (e.g. background
+    // threads still holding the fd) cannot block the caller indefinitely.
+    // On timeout we return whatever we received so far (empty string here since
+    // `readPromise` is all-or-nothing with `Response.text()`).
+    const timeoutPromise = new Promise((resolve) => {
+        setTimeout(() => resolve(""), opts.timeoutMs);
+    });
+    return Promise.race([readPromise, timeoutPromise]);
+}
+/**
+ * Spawn the agent CLI described by `profile` with `prompt` (forwarded as
+ * the last positional arg by default) and return a structured result.
+ *
+ * The `prompt` argument is appended to `profile.args` (and `options.args`)
+ * unless it is `undefined`. Pass `prompt = ""` to forward an explicit
+ * empty positional, or pass extra args via `options.args`.
+ *
+ * Failure modes (see {@link AgentFailureReason}):
+ *
+ *   • `spawn_failed`  — `Bun.spawn` threw synchronously.
+ *   • `timeout`       — exceeded the resolved timeout.
+ *   • `non_zero_exit` — child exited with a non-zero code.
+ *   • `parse_error`   — `parseOutput === "json"` and stdout was not JSON.
+ *
+ * `ok === true` requires exit code 0 and (if `parseOutput === "json"`)
+ * a successful `JSON.parse`.
+ */
+export async function runAgent(profile, prompt, options = {}) {
+    const stdioMode = options.stdio ?? profile.stdio;
+    const timeoutMs = options.timeoutMs ?? profile.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    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);
+    const start = Date.now();
+    let proc;
+    try {
+        const spawnFn = resolveSpawnFn(options);
+        proc = spawnFn([profile.bin, ...args], {
+            stdin: stdioMode === "captured" ? (options.stdin !== undefined ? "pipe" : "ignore") : "inherit",
+            stdout: stdioMode === "captured" ? "pipe" : "inherit",
+            stderr: stdioMode === "captured" ? "pipe" : "inherit",
+            env,
+            ...(options.cwd ? { cwd: options.cwd } : {}),
+            // Spawn in its own process group so killGroup(-pid, signal) reaches all
+            // descendants (e.g. the .opencode binary that opencode's node wrapper forks).
+            // Only applied in captured mode — interactive mode inherits the parent
+            // terminal's process group intentionally.
+            ...(stdioMode === "captured" ? { detached: true } : {}),
+        });
+    }
+    catch (err) {
+        const durationMs = Date.now() - start;
+        return {
+            ok: false,
+            exitCode: null,
+            stdout: "",
+            stderr: "",
+            durationMs,
+            reason: "spawn_failed",
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+    // Hard timeout. We prefer SIGTERM, then SIGKILL if SIGTERM is ignored,
+    // but Bun.spawn only exposes a single .kill() — one signal is enough
+    // for the structured-failure contract.
+    //
+    // BUG-M3: only flag `timedOut` when the child has not already exited. A
+    // timer firing in the same microtask as `proc.exited` resolving could
+    // otherwise label a clean exit as a timeout.
+    let timedOut = false;
+    const timer = setTimeoutImpl(() => {
+        if (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)
+                return;
+            killGroup(proc, "SIGKILL");
+        }, 5000);
+    }, timeoutMs);
+    // Stream-drain timeout: the overall wall-clock budget plus a 2 s grace
+    // period. When a process is killed via SIGTERM/SIGKILL (from our timeout
+    // handler or from outside) some runtimes keep the pipe write-end open in
+    // background threads, which would cause `Response.text()` to block forever.
+    // Capping stream draining at `timeoutMs + 2 000 ms` ensures the caller
+    // never hangs past the wall budget regardless of subprocess pipe behaviour.
+    const streamDrainTimeoutMs = timeoutMs + 2_000;
+    const stdoutPromise = stdioMode === "captured"
+        ? readStream(proc.stdout ?? null, { timeoutMs: streamDrainTimeoutMs })
+        : Promise.resolve("");
+    const stderrPromise = stdioMode === "captured"
+        ? readStream(proc.stderr ?? null, { timeoutMs: streamDrainTimeoutMs })
+        : Promise.resolve("");
+    // Optional stdin payload (captured mode only).
+    //
+    // BUG-H1: race the stdin write/close against `proc.exited` and the
+    // timeout timer. If the child never drains stdin, an unraced
+    // `await writer.write()` would block forever and prevent `runAgent`
+    // from ever returning.
+    if (options.stdin !== undefined && stdioMode === "captured" && proc.stdin) {
+        const stdinPayload = options.stdin;
+        const stdinStream = proc.stdin;
+        const stdinDone = (async () => {
+            try {
+                const writer = stdinStream.getWriter();
+                const bytes = new TextEncoder().encode(stdinPayload);
+                await writer.write(bytes);
+                await writer.close();
+            }
+            catch {
+                // Best-effort: ignore stdin write failures, the child will get EOF.
+            }
+        })();
+        // Resolve as soon as either the write completes or the child exits.
+        // We don't await the result — only that one of the two has settled —
+        // so a stuck writer cannot keep us pinned past the timeout.
+        await Promise.race([stdinDone, proc.exited.catch(() => undefined)]);
+    }
+    let exitCode = null;
+    try {
+        exitCode = await proc.exited;
+    }
+    catch (err) {
+        clearTimeoutImpl(timer);
+        // BUG-H2: drain stream readers before the early return so they don't
+        // surface as unhandled rejections after the function resolves.
+        // The streams already carry a built-in drain timeout so this allSettled
+        // will not block indefinitely.
+        await Promise.allSettled([stdoutPromise, stderrPromise]);
+        const durationMs = Date.now() - start;
+        return {
+            ok: false,
+            exitCode: null,
+            stdout: "",
+            stderr: "",
+            durationMs,
+            reason: "spawn_failed",
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+    clearTimeoutImpl(timer);
+    const [stdout, stderr] = await Promise.all([stdoutPromise, stderrPromise]);
+    const durationMs = Date.now() - start;
+    if (timedOut) {
+        return {
+            ok: false,
+            exitCode,
+            stdout,
+            stderr,
+            durationMs,
+            reason: "timeout",
+            error: `agent CLI "${profile.name}" timed out after ${timeoutMs}ms`,
+        };
+    }
+    if (exitCode !== 0) {
+        return {
+            ok: false,
+            exitCode,
+            stdout,
+            stderr,
+            durationMs,
+            reason: "non_zero_exit",
+            error: `agent CLI "${profile.name}" exited with code ${exitCode}`,
+        };
+    }
+    if (parseOutput === "json" && stdioMode === "captured") {
+        try {
+            const parsed = JSON.parse(stdout);
+            return { ok: true, exitCode, stdout, stderr, durationMs, parsed };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                exitCode,
+                stdout,
+                stderr,
+                durationMs,
+                reason: "parse_error",
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    return { ok: true, exitCode, stdout, stderr, durationMs };
+}

package/dist/{integrations → src/integrations}/github.js

@@ -2,8 +2,13 @@ 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"]);
 function readGithubTokenFromEnv() {
-    const token = process.env.GITHUB_TOKEN?.trim() || process.env.GH_TOKEN?.trim();
-    return token || undefined;
+    if (process.env.GITHUB_TOKEN !== undefined) {
+        return process.env.GITHUB_TOKEN.trim();
+    }
+    if (process.env.GH_TOKEN !== undefined) {
+        return process.env.GH_TOKEN.trim();
+    }
+    return undefined;
 }
 function readGithubTokenFromGhCli() {
     const result = childProcess.spawnSync("gh", ["auth", "token"], {
@@ -17,7 +22,8 @@ function readGithubTokenFromGhCli() {
     return token || undefined;
 }
 function resolveGithubToken() {
-    return readGithubTokenFromEnv() ?? readGithubTokenFromGhCli();
+    const token = readGithubTokenFromEnv();
+    return token !== undefined ? token || undefined : readGithubTokenFromGhCli();
 }
 /**
  * Build headers for GitHub API requests.

package/dist/{integrations → src/integrations}/lockfile.js

@@ -3,34 +3,9 @@ import path from "node:path";
 import { getConfigDir } from "../core/config";
 // ── Paths ───────────────────────────────────────────────────────────────────
 const LOCKFILE_NAME = "akm.lock";
-const LEGACY_LOCKFILE_NAME = "stash.lock";
 function getLockfilePath() {
     return path.join(getConfigDir(), LOCKFILE_NAME);
 }
-function getLegacyLockfilePath() {
-    return path.join(getConfigDir(), LEGACY_LOCKFILE_NAME);
-}
-/**
- * One-time migration: if the new `akm.lock` does not exist but the legacy
- * `stash.lock` does, copy it across so installed-stash tracking survives the
- * rename. Best-effort; failures are silent because the lockfile loader treats
- * a missing file as an empty lockfile.
- */
-function migrateLegacyLockfileIfNeeded() {
-    const newPath = getLockfilePath();
-    const legacyPath = getLegacyLockfilePath();
-    try {
-        if (fs.existsSync(newPath))
-            return;
-        if (!fs.existsSync(legacyPath))
-            return;
-        fs.mkdirSync(path.dirname(newPath), { recursive: true });
-        fs.copyFileSync(legacyPath, newPath);
-    }
-    catch {
-        /* best-effort — fall through to empty lockfile */
-    }
-}
 // ── Lock sentinel ────────────────────────────────────────────────────────────
 const LOCK_MAX_RETRIES = 3;
 const LOCK_RETRY_DELAY_MS = 100;
@@ -100,7 +75,6 @@ function releaseLockSentinel() {
 }
 // ── Read / Write ────────────────────────────────────────────────────────────
 export function readLockfile() {
-    migrateLegacyLockfileIfNeeded();
     const lockfilePath = getLockfilePath();
     try {
         const raw = JSON.parse(fs.readFileSync(lockfilePath, "utf8"));

package/dist/{llm → src/llm}/client.js

@@ -8,6 +8,36 @@
  * `llm.ts` re-exports everything from this module for backward compatibility.
  */
 import { fetchWithTimeout } from "../core/common";
+/** Maximum length of an LLM error response body included in thrown errors. */
+const ERROR_BODY_MAX_LEN = 200;
+/**
+ * Redact credential-shaped substrings from an upstream error body before
+ * including it in a thrown Error. The body is also trimmed to a fixed length
+ * so that a verbose provider response cannot leak large amounts of context.
+ *
+ * Targets:
+ *  - `Bearer <token>` headers echoed back by the provider
+ *  - `sk-…` / `sk_…` style API keys (OpenAI / Anthropic-shaped)
+ *  - `key-…` / `key_…` shorthand keys
+ *  - `"api_key": "…"` / `"apiKey": "…"` JSON fields
+ */
+export function redactErrorBody(input) {
+    if (!input)
+        return "";
+    let out = input
+        // Bearer tokens (case-insensitive)
+        .replace(/\bBearer\s+[A-Za-z0-9._\-+/=]+/gi, "Bearer [REDACTED]")
+        // sk-/sk_ style keys
+        .replace(/\bsk[-_][A-Za-z0-9._-]{6,}/g, "[REDACTED]")
+        // key-/key_ shorthand keys
+        .replace(/\bkey[-_][A-Za-z0-9._-]{6,}/g, "[REDACTED]")
+        // JSON-style "api_key": "...", "apiKey": "...", "api-key": "..."
+        .replace(/("(?:api[_-]?key|apiKey|authorization|token)"\s*:\s*")([^"]*)(")/gi, "$1[REDACTED]$3");
+    if (out.length > ERROR_BODY_MAX_LEN) {
+        out = `${out.slice(0, ERROR_BODY_MAX_LEN)}…`;
+    }
+    return out;
+}
 export async function chatCompletion(config, messages, options) {
     const headers = { "Content-Type": "application/json" };
     if (config.apiKey) {
@@ -24,8 +54,9 @@ export async function chatCompletion(config, messages, options) {
         }),
     });
     if (!response.ok) {
-        const body = await response.text().catch(() => "");
-        throw new Error(`LLM request failed (${response.status}): ${body}`);
+        const rawBody = await response.text().catch(() => "");
+        const safeBody = redactErrorBody(rawBody);
+        throw new Error(`LLM request failed (${response.status}) ${config.endpoint}: ${safeBody}`);
     }
     const json = (await response.json());
     return json.choices?.[0]?.message?.content?.trim() ?? "";

package/dist/{llm → src/llm}/embedders/remote.js

@@ -5,7 +5,11 @@
  * vectors so the scoring pipeline's L2-to-cosine conversion is correct.
  */
 import { fetchWithTimeout, isHttpUrl } from "../../core/common";
-const REMOTE_BATCH_SIZE = 100;
+const DEFAULT_REMOTE_BATCH_SIZE = 100;
+/** Cheap token estimator: 4 chars ≈ 1 token. Used in verbose logging and error messages. */
+export function estimateTokenCount(text) {
+    return Math.round(text.length / 4);
+}
 export class RemoteEmbedder {
     config;
     constructor(config) {
@@ -20,6 +24,10 @@ export class RemoteEmbedder {
         if (this.config.dimension) {
             body.dimensions = this.config.dimension;
         }
+        const ollamaOpts = resolveOllamaOptions(this.config);
+        if (ollamaOpts) {
+            body.options = ollamaOpts;
+        }
         const response = await fetchWithTimeout(normalizeEmbeddingEndpoint(this.config.endpoint), {
             method: "POST",
             headers,
@@ -40,8 +48,10 @@ export class RemoteEmbedder {
             return [];
         const results = [];
         const headers = this.buildHeaders();
-        for (let i = 0; i < texts.length; i += REMOTE_BATCH_SIZE) {
-            const batch = texts.slice(i, i + REMOTE_BATCH_SIZE);
+        const ollamaOpts = resolveOllamaOptions(this.config);
+        const batchSize = this.config.batchSize ?? DEFAULT_REMOTE_BATCH_SIZE;
+        for (let i = 0; i < texts.length; i += batchSize) {
+            const batch = texts.slice(i, i + batchSize);
             const body = {
                 input: batch,
                 model: this.config.model,
@@ -49,6 +59,9 @@ export class RemoteEmbedder {
             if (this.config.dimension) {
                 body.dimensions = this.config.dimension;
             }
+            if (ollamaOpts) {
+                body.options = ollamaOpts;
+            }
             const response = await fetchWithTimeout(normalizeEmbeddingEndpoint(this.config.endpoint), {
                 method: "POST",
                 headers,
@@ -115,6 +128,27 @@ function embeddingEndpointPathHint(endpoint) {
     }
     return "";
 }
+/**
+ * Resolve Ollama-native `options` from the embedding config.
+ *
+ * Resolution order:
+ *   1. `ollamaOptions` — forwarded verbatim (explicit opt-in, takes precedence).
+ *   2. `contextLength` — wrapped as `{ num_ctx: contextLength }`.
+ *   3. Neither set → returns `undefined` (no `options` field in the request body).
+ *
+ * These options are only meaningful for Ollama's native `/api/embed` endpoint.
+ * OpenAI-compatible endpoints ignore unknown request fields, so passing them to
+ * other providers is harmless but has no effect.
+ */
+function resolveOllamaOptions(config) {
+    if (config.ollamaOptions && Object.keys(config.ollamaOptions).length > 0) {
+        return config.ollamaOptions;
+    }
+    if (config.contextLength) {
+        return { num_ctx: config.contextLength };
+    }
+    return undefined;
+}
 /** Check whether an EmbeddingConnectionConfig has a valid remote endpoint. */
 export function hasRemoteEndpoint(config) {
     return isHttpUrl(config.endpoint);