akm-cli 0.9.7 → 0.9.8-beta.2

package/dist/integrations/harnesses/openhands/result-extractor.js

@@ -1,15 +1,56 @@
 // 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/.
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
+/**
+ * OpenHands CLI result extractor (P2, plan §"The adapter contract" step 3 /
+ * §"Structured-output normalization", tier "native-json").
+ *
+ * Normalizes one raw {@link AgentRunResult} from a headless
+ * `openhands --headless --json` run into `{ text, sessionId? }` — the
+ * {@link AgentResultExtraction} seam. The engine's shared schema-validation /
+ * retry-until-valid loop runs *after* this; the extractor only strips
+ * transport framing.
+ *
+ * With `--json` OpenHands emits ONE JSON event per stdout line — its
+ * action/observation event stream, e.g.:
+ *
+ *   {"id":0,"source":"user","action":"message","args":{"content":"<task>"},"message":"<task>"}
+ *   {"id":1,"source":"agent","action":"run","args":{"command":"ls"},"message":"Running command: ls"}
+ *   {"id":2,"source":"agent","observation":"run","content":"README.md","message":"Command `ls` executed."}
+ *   {"id":3,"source":"agent","action":"message","args":{"content":"<answer>"},"message":"<answer>"}
+ *   {"id":4,"source":"agent","action":"finish","args":{"final_thought":"<answer>","outputs":{}},"message":"..."}
+ *
+ * Extraction rules ("parse JSONL final message" per the capability matrix):
+ *   - text: the LAST agent-sourced *message-bearing* event wins. Only two
+ *     event kinds carry the agent's answer: `action:"message"`
+ *     (`args.content`, falling back to the top-level `message` mirror) and
+ *     `action:"finish"` (`args.final_thought`/`args.thought`, falling back to
+ *     `message`). User echoes, observations, and tool actions (`run`, `edit`,
+ *     …, whose `message` is progress noise like "Running command: ls") never
+ *     contribute.
+ *   - sessionId: the FIRST id-bearing event supplies it (`session_id`,
+ *     `sessionId`, `sid`, `conversation_id`), falling back to any sessionId
+ *     the spawn layer already attached. Stored opportunistically on the unit
+ *     row; per the matrix OpenHands resume is workspace-state, so akm never
+ *     depends on it (plan §"Session, MCP, and identity across harnesses").
+ *
+ * Also handled, so version churn stays contained in this one file (per the
+ * adapter contract):
+ *   - a single whole-stdout JSON document (or a spawn-layer `result.parsed`
+ *     value) is interpreted with the same rules;
+ *   - plain text (no `--json`, or an unrecognized envelope) passes through
+ *     trimmed — the engine's embedded-JSON parsing still runs downstream for
+ *     schema units;
+ *   - non-JSON banner lines interleaved in the stream are skipped.
+ *
+ * Registered: `openhandsResultExtractor` is `OpenhandsHarness.resultExtractor`
+ * (`./index.ts`); the engine resolves it via `getHarness()` in
+ * `workflows/exec/native-executor.ts` to normalize agent-unit stdout before
+ * schema validation.
+ */
+import { asNonEmptyString, isRecord, tryParseJson } from "../../../core/common.js";
 /** Keys that may carry the harness-native session id, in precedence order. */
 const SESSION_KEYS = ["session_id", "sessionId", "sid", "conversation_id"];
-/** Return a non-empty string, else undefined. */
-function nonEmptyString(value) {
-    return typeof value === "string" && value.length > 0 ? value : undefined;
-}
 /**
  * Extract the agent's answer text from one parsed OpenHands event, if the
  * event is one of the two message-bearing kinds (see module doc). Everything
@@ -25,31 +66,22 @@ function extractAgentText(event) {
         return undefined;
     const args = isRecord(event.args) ? event.args : undefined;
     if (event.action === "message") {
-        return nonEmptyString(args?.content) ?? nonEmptyString(event.message);
+        return asNonEmptyString(args?.content) ?? asNonEmptyString(event.message);
     }
     if (event.action === "finish") {
-        return nonEmptyString(args?.final_thought) ?? nonEmptyString(args?.thought) ?? nonEmptyString(event.message);
+        return asNonEmptyString(args?.final_thought) ?? asNonEmptyString(args?.thought) ?? asNonEmptyString(event.message);
     }
     return undefined;
 }
 /** Extract a harness-native session id from one parsed JSON value, if any. */
 function extractSessionId(event) {
     for (const key of SESSION_KEYS) {
-        const candidate = nonEmptyString(event[key]);
+        const candidate = asNonEmptyString(event[key]);
         if (candidate)
             return candidate;
     }
     return undefined;
 }
-/** JSON.parse that returns undefined instead of throwing. */
-function tryParseJson(raw) {
-    try {
-        return JSON.parse(raw);
-    }
-    catch {
-        return undefined;
-    }
-}
 /**
  * Normalize a raw openhands run result into `{ text, sessionId? }`.
  * See the module doc for the stdout shapes handled.

package/dist/integrations/harnesses/pi/result-extractor.js

@@ -1,9 +1,51 @@
 // 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/.
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
+/**
+ * Pi coding-agent CLI result extractor (P2, plan §"The adapter contract"
+ * step 3 / §"Structured-output normalization", tier "native-json").
+ *
+ * Normalizes one raw {@link AgentRunResult} from a headless `pi` run into
+ * `{ text, sessionId? }` — the {@link AgentResultExtraction} seam. The
+ * engine's shared schema-validation / retry-until-valid loop runs *after*
+ * this; the extractor only strips transport framing.
+ *
+ * With `--mode json` (the capability matrix's structured mode) Pi emits ONE
+ * JSON event per stdout line — the agent-session event stream, e.g.:
+ *
+ *   {"type":"session_start","session_id":"<id>"}
+ *   {"type":"agent_start"}
+ *   {"type":"message_start","message":{"role":"assistant","content":[]}}
+ *   {"type":"message_end","message":{"role":"assistant","content":[{"type":"text","text":"<text>"}]}}
+ *   {"type":"agent_end","messages":[{"role":"assistant","content":[...]}]}
+ *
+ * Extraction rules:
+ *   - text: the LAST assistant text-bearing event wins (`message_end` bodies;
+ *     an `agent_end` transcript's final assistant message; tolerant flat
+ *     `role:"assistant"` events). User-role echoes / tool events never
+ *     contribute. Assistant content blocks are flattened; non-text blocks
+ *     (thinking, tool use) are skipped.
+ *   - sessionId: the FIRST session-id-bearing event supplies it (snake_case /
+ *     camelCase variants, plus `id` on `session*`-typed events), falling back
+ *     to any sessionId the spawn layer already attached. Stored
+ *     opportunistically on the unit row for `--session <id>` resume; akm
+ *     never depends on it (plan §"Session, MCP, and identity").
+ *
+ * Also handled, so version churn stays contained in this one file (per the
+ * adapter contract):
+ *   - a single whole-stdout JSON document (or a spawn-layer `result.parsed`
+ *     value) is interpreted with the same rules;
+ *   - plain text (no `--mode json`, or an unrecognized envelope) passes
+ *     through trimmed — the engine's embedded-JSON parsing still runs
+ *     downstream for schema units;
+ *   - non-JSON banner lines interleaved in the stream are skipped.
+ *
+ * Registered: `piResultExtractor` is `PiHarness.resultExtractor`
+ * (`./index.ts`); the engine resolves it via `getHarness()` in
+ * `workflows/exec/native-executor.ts` to normalize agent-unit stdout before
+ * schema validation.
+ */
+import { isRecord, tryParseJson } from "../../../core/common.js";
 /** Keys that may carry the harness-native session id, in precedence order. */
 const SESSION_KEYS = ["session_id", "sessionId", "session"];
 /**
@@ -73,15 +115,6 @@ function extractSessionId(event) {
     }
     return undefined;
 }
-/** JSON.parse that returns undefined instead of throwing. */
-function tryParseJson(raw) {
-    try {
-        return JSON.parse(raw);
-    }
-    catch {
-        return undefined;
-    }
-}
 /**
  * Normalize a raw pi run result into `{ text, sessionId? }`.
  * See the module doc for the stdout shapes handled.

package/dist/integrations/lockfile.js

@@ -186,20 +186,6 @@ export async function writeLockfile(entries) {
         release();
     }
 }
-/** Replace one exact parsed lock generation while the lockfile sentinel is held. */
-export async function compareAndSwapLockfile(expected, desired) {
-    const release = await acquireLockSentinel();
-    try {
-        const current = readLockfileOrThrow();
-        if (JSON.stringify(current) !== JSON.stringify(expected))
-            return false;
-        writeLockfileUnlocked(desired);
-        return true;
-    }
-    finally {
-        release();
-    }
-}
 /**
  * Publish an update from one exact raw + parsed lockfile generation and return
  * the exact bytes that were written. Formatting-only concurrent edits are a

package/dist/integrations/session-logs/index.js

@@ -39,7 +39,6 @@ for (const provider of HARNESSES) {
         throw new Error(`[akm] session-log provider "${provider.name}" is not registered as a sessionLogs harness in HARNESS_REGISTRY (src/integrations/harnesses). Add it there.`);
     }
 }
-const ERROR_PATTERNS = /error|failed|exception|cannot|undefined|null pointer|ENOENT|timeout/i;
 /**
  * Returns all available session log harnesses for the current machine.
  * Add new harnesses to HARNESSES to support additional agent runtimes.
@@ -53,83 +52,3 @@ export function normalizeSessionTopic(text) {
         return undefined;
     return normalized.slice(0, 60);
 }
-export function aggregateSessionEvents(events) {
-    const counts = new Map();
-    for (const event of events) {
-        const topic = normalizeSessionTopic(event.text);
-        if (!topic)
-            continue;
-        const isFailurePattern = ERROR_PATTERNS.test(topic);
-        if (!isFailurePattern)
-            continue;
-        const existing = counts.get(topic) ?? {
-            count: 0,
-            isFailurePattern,
-            sources: new Set(),
-            topic,
-        };
-        existing.count += 1;
-        existing.isFailurePattern = existing.isFailurePattern || isFailurePattern;
-        existing.sources.add(event.harness);
-        counts.set(topic, existing);
-    }
-    return [...counts.values()]
-        .filter((entry) => entry.count >= 2)
-        .sort((a, b) => b.count - a.count || a.topic.localeCompare(b.topic))
-        .slice(0, 15)
-        .map((entry) => ({
-        topic: entry.topic,
-        frequency: entry.count,
-        source: [...entry.sources].sort().join(","),
-        isFailurePattern: entry.isFailurePattern,
-    }));
-}
-/**
- * Collect normalized session events from a set of harnesses for the health
- * candidate scan (#568).
- *
- * Pipeline selection per harness:
- *   - Drive the richer `listSessions()` + `readSession()` pipeline. `readSession` flattens
- *     structured content — tool calls, assistant content blocks, thinking,
- *     tool_result — into event text (e.g. ClaudeCodeProvider's `parseClaudeEvent`
- *     surfaces `[tool:*]` / `[tool_result]` blocks that the legacy flat
- *     `readEvents` scan drops entirely). This is what lets health advisories see
- *     repeated tool failures / long runs that the flat scan hid.
- *
- * Extracted as a pure function (harnesses injected) so it is unit-testable
- * without touching the real on-disk session-log locations.
- *
- * `maxSessionsPerHarness` bounds the path: `readSession()` reads each
- * session file in full. On a machine with a
- * deep `~/.claude/projects` history a 30-day window can hold hundreds of
- * multi-MB session files, and reading+parsing every one in full made the
- * health command (`akm health`, which calls this synchronously) blow past its
- * latency budget. `listSessions()` returns summaries sorted newest-first, so
- * capping to the most-recent N sessions per harness keeps the richer signal
- * for what actually matters (recent activity) while bounding cost.
- */
-const DEFAULT_MAX_SESSIONS_PER_HARNESS = 50;
-export function collectSessionEvents(harnesses, sinceMs, maxSessionsPerHarness = DEFAULT_MAX_SESSIONS_PER_HARNESS) {
-    const events = [];
-    for (const harness of harnesses) {
-        try {
-            // Enumerate sessions cheaply, then read each one's full structured event
-            // stream. There is no parallel flat-log parser.
-            const summaries = harness.listSessions({ sinceMs });
-            // summaries are newest-first; bound the full-file reads (see doc above).
-            for (const summary of summaries.slice(0, maxSessionsPerHarness)) {
-                try {
-                    const session = harness.readSession(summary);
-                    events.push(...session.events);
-                }
-                catch {
-                    // a single unreadable session is non-fatal
-                }
-            }
-        }
-        catch {
-            // individual harness failures are non-fatal
-        }
-    }
-    return events;
-}

package/dist/llm/client.js

@@ -423,18 +423,6 @@ async function chatCompletionAttemptOnce(config, messages, options, timeoutMs, i
     }
 }
 // ── Availability check ──────────────────────────────────────────────────────
-/**
- * Check if the LLM endpoint is reachable.
- */
-export async function isLlmAvailable(config) {
-    try {
-        const result = await chatCompletion(config, [{ role: "user", content: "Respond with just the word: ok" }]);
-        return result.length > 0;
-    }
-    catch {
-        return false;
-    }
-}
 // ── Reachability probe ──────────────────────────────────────────────────────
 /**
  * Best-effort reachability check with an error message, for setup's optional

package/dist/llm/memory-infer.js

@@ -22,8 +22,6 @@ import { toErrorMessage } from "../core/common.js";
 import { parseEmbeddedJsonResponse } from "../core/parse.js";
 import { warn } from "../core/warn.js";
 import { callStructured } from "./structured-call.js";
-/** Hard cap on body chars sent to the model — pragmatic and matches `runLlmEnrich`. */
-const MAX_BODY_CHARS = 4000;
 const SYSTEM_PROMPT = memoryInferSystemPrompt;
 const USER_PROMPT_PREFIX = memoryInferUserPrompt;
 const PROMPT_PLACEHOLDERS = new Set([
@@ -74,7 +72,7 @@ export async function compressMemoryToDerivedMemory(llmRunner, body, signal, akm
     const trimmedBody = body.trim();
     if (!trimmedBody)
         return undefined;
-    const userPrompt = `${USER_PROMPT_PREFIX}${trimmedBody.slice(0, MAX_BODY_CHARS)}`;
+    const userPrompt = `${USER_PROMPT_PREFIX}${trimmedBody}`;
     // Memory inference is always gated: no config closes the gate instead of
     // taking callStructured's ungated path for direct callers.
     if (!akmConfig) {

package/dist/llm/usage-telemetry.js

@@ -25,6 +25,7 @@
  * `undefined` outside any `withLlmStage` scope.
  */
 import { AsyncLocalStorage } from "node:async_hooks";
+import { asNonEmptyString } from "../core/common.js";
 const attributionStorage = new AsyncLocalStorage();
 let usageSink;
 /**
@@ -85,9 +86,6 @@ export function emitLlmUsage(record) {
 function asFiniteNonNegative(value) {
     return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
 }
-function asNonEmptyString(value) {
-    return typeof value === "string" && value.length > 0 ? value : undefined;
-}
 function asLlmUsageErrorCode(value) {
     switch (value) {
         case "rate_limited":

package/dist/registry/create-provider-registry.js

@@ -17,6 +17,10 @@ export function createProviderRegistry() {
         resolve(type) {
             return map.get(type) ?? null;
         },
+        /** Removes a registration. No-op if `type` was never registered. */
+        unregister(type) {
+            map.delete(type);
+        },
         /** Snapshot of all registered keys. Iteration order matches insertion order. */
         list() {
             return [...map.keys()];

package/dist/registry/factory.js

@@ -24,3 +24,7 @@ export function registerRegistryProvider(type, factory) {
 export function resolveRegistryProviderFactory(type) {
     return registry.resolve(type);
 }
+/** Test-only seam: removes a registration made with {@link registerRegistryProvider}. */
+export function unregisterRegistryProvider(type) {
+    registry.unregister(type);
+}

package/dist/registry/resolve.js

@@ -298,14 +298,18 @@ export function trustedNpmTarballHosts() {
     const hosts = new Set([DEFAULT_NPM_REGISTRY_HOST]);
     const override = process.env.AKM_NPM_REGISTRY?.trim();
     if (override) {
+        // A malformed override must not be silently ignored (falling back to the
+        // public registry as though nothing was configured) — that would install
+        // from the wrong registry without telling the operator (R-035).
+        let overrideHost;
         try {
-            const overrideHost = new URL(override).hostname.toLowerCase();
-            if (overrideHost)
-                hosts.add(overrideHost);
+            overrideHost = new URL(override).hostname.toLowerCase();
         }
         catch {
-            // Ignore unparseable overrides; the default host still applies.
+            throw new UsageError(`AKM_NPM_REGISTRY is set to an invalid URL: ${override}`);
         }
+        if (overrideHost)
+            hosts.add(overrideHost);
     }
     return hosts;
 }
@@ -358,14 +362,18 @@ export function npmArtifactNetworkPolicy(artifact) {
 function npmMetadataRegistry() {
     const override = process.env.AKM_NPM_REGISTRY?.trim();
     if (override) {
+        // A malformed override must not be silently ignored (falling back to the
+        // public registry as though nothing was configured) — that would install
+        // from the wrong registry without telling the operator (R-035).
+        let url;
         try {
-            const url = new URL(override);
-            const base = `${url.origin}${url.pathname === "/" ? "" : url.pathname}`;
-            return { baseUrl: base.replace(/\/+$/, ""), allowPrivateRegistryOrigin: true };
+            url = new URL(override);
         }
         catch {
-            // Ignore unparseable overrides; fall back to the public registry.
+            throw new UsageError(`AKM_NPM_REGISTRY is set to an invalid URL: ${override}`);
         }
+        const base = `${url.origin}${url.pathname === "/" ? "" : url.pathname}`;
+        return { baseUrl: base.replace(/\/+$/, ""), allowPrivateRegistryOrigin: true };
     }
     return { baseUrl: `https://${DEFAULT_NPM_REGISTRY_HOST}`, allowPrivateRegistryOrigin: false };
 }
@@ -490,6 +498,13 @@ function resolveGitRevisionFromRemote(url, requestedRef) {
 }
 async function resolveGitArtifact(parsed) {
     const resolvedRevision = resolveGitRevisionFromRemote(parsed.url, parsed.requestedRef);
+    if (!resolvedRevision) {
+        // Unlike the GitHub path (which falls back to the REST API on a failed
+        // `git ls-remote`), a plain git source has no fallback resolver — an
+        // unresolved revision here would silently disable the post-clone
+        // revision-integrity check in `verifyClonedRevision` (R-011).
+        throw new Error(`Unable to resolve ${parsed.requestedRef ?? "HEAD"} for ${parsed.url} via 'git ls-remote'; refusing to install without a verifiable revision.`);
+    }
     return {
         id: parsed.id,
         source: parsed.source,

package/dist/runtime.js

@@ -250,18 +250,6 @@ export function semverOrder(a, b) {
     const semver = nodeRequire("semver");
     return semver.compare(a, b);
 }
-// ── Module resolution ───────────────────────────────────────────────────────
-/**
- * Resolve a module specifier without loading it, relative to `from`. On Bun
- * uses `Bun.resolveSync`; on Node uses `require.resolve`. Throws when the
- * specifier cannot be resolved (mirroring both underlying APIs).
- */
-export function resolveModule(spec, from) {
-    if (isBun) {
-        return bunGlobal().resolveSync(spec, from);
-    }
-    return nodeRequire.resolve(spec, { paths: [from] });
-}
 // ── Filesystem paths ────────────────────────────────────────────────────────
 /**
  * The directory of the module identified by `importMetaUrl`. Replaces