akm-opencode 0.5.1 → 0.6.0

package/README.md

@@ -41,14 +41,14 @@ fails silently when `akm` is not on PATH — the TUI is never affected.
 
 | Event | What happens |
 | --- | --- |
-| **`session.created`** (event hook) | Warms the stash index in the background and caches `akm hints` plus active workflow status for the next system transform so the agent knows the CLI surface area at turn 0. |
-| **`chat.message`** | Runs `akm curate "<prompt>"` on each user message (prompts shorter than `AKM_CURATE_MIN_CHARS` are skipped). The top matches are stored for injection. Memory intents (prompts mentioning "remember" / "memory") are tracked in the session buffer. |
+| **`session.created`** (event hook) | Warms the stash index in the background, caches `akm hints` plus active workflow status, and runs a scoped `akm curate --run <sessionID>` so fresh sessions see relevant stash context before the first user message. |
+| **`chat.message`** | Runs `akm curate "<prompt>" --run <sessionID>` on each user message (prompts shorter than `AKM_CURATE_MIN_CHARS` are skipped). The top matches are stored for injection. Memory intents (prompts mentioning "remember" / "memory") are tracked in the session buffer. |
 | **`experimental.chat.system.transform`** | Appends cached hints, active workflow state, the last curator report, and the current prompt's curated context to the model's system prompt. Hints and workflow state are re-injected after transcript compaction. |
 | **`tool.execute.before`** (`akm_*` tools) | Blocks destructive or sensitive operations until `confirm:true` is provided. |
 | **`tool.execute.after`** (`akm_*` tools) | Logs asset usage, accumulates refs into the session buffer, records `akm feedback <ref> --positive` / `--negative` asynchronously with per-call dedupe, checkpoints memories every `AKM_MEMORY_CHECKPOINT_EVERY` successful asset-touching tool calls, and scans child-agent free text for additional refs. |
 | **`experimental.session.compacting`** | Pushes hints, curated context, active workflows, and the last curator report into the compaction prompt so they survive transcript shrinking. |
 | **`shell.env`** | Exposes `AKM_STASH_DIR`, `AKM_PROJECT`, and `AKM_PLUGIN_VERSION` to shell tools so plain `akm` calls inherit the right context. |
-| **`stop`** / **`session.idle`** / **`session.compacted`** / **`session.deleted`** | Flushes the per-session buffer into a `memory:opencode-session-YYYYMMDD-<sid>` memory so every meaningful session contributes durable context for future searches. Requires at least two observations before persisting. |
+| **`stop`** / **`session.idle`** / **`session.compacted`** / **`session.deleted`** | Flushes the per-session buffer into a `memory:opencode-session-YYYYMMDD-<sid>` memory so every meaningful session contributes durable context for future searches. Requires at least two observations before persisting. When `AKM_INDEX_ON_SESSION_END=1`, the hook follows a successful flush with `akm index` so upstream inference/graph passes run immediately. |
 
 ### Environment overrides
 
@@ -58,9 +58,11 @@ fails silently when `akm` is not on PATH — the TUI is never affected.
 | `AKM_AUTO_FEEDBACK` | `1` | Set to `0` to disable automatic `akm feedback` on tool success/failure. |
 | `AKM_AUTO_HINTS` | `1` | Set to `0` to skip injecting `akm hints` at session start. |
 | `AKM_AUTO_MEMORY` | `1` | Set to `0` to disable automatic session-summary memories. |
+| `AKM_INDEX_ON_SESSION_END` | `0` | Set to `1` to run `akm index` after a session-end memory is captured. |
 | `AKM_CURATE_LIMIT` | `5` | Max curated results injected into context per prompt. |
 | `AKM_CURATE_MIN_CHARS` | `16` | Minimum prompt length before curation runs. |
 | `AKM_CURATE_TIMEOUT` | `8` | Wall-clock seconds for `akm` invocations inside hooks. |
+| `AKM_CONTEXT_BUDGET_CHARS` | `4000` | Max total characters injected into system/compaction context for a single turn. |
 | `AKM_CURATOR_CONTEXT_MAX_CHARS` | `4000` | Max cached curator-report characters re-injected into system/compaction context; the full report is still persisted as memory. |
 | `AKM_MEMORY_CHECKPOINT_EVERY` | `8` | Number of successful asset-touching tool calls between mid-session checkpoint memories. |
 | `AKM_RETROSPECTIVE_FEEDBACK_PATTERN` | `\b(thanks|perfect|worked)\b` | Case-insensitive regex used for lightweight positive retrospective feedback on the most recent refs. |
@@ -112,7 +114,7 @@ At least one of `ref` or `query` is required.
 
 ## Prerequisites
 
-When the plugin loads, it runs `bun install -g akm-cli@latest` so it always picks up the latest published npm package. It then prefers the Bun-installed binary and falls back to an existing `akm` on PATH when needed. It does not run the standalone shell installers automatically.
+When the plugin loads, it checks the installed `akm` version first and only runs `bun install -g akm-cli@latest` when `akm` is missing or older than the latest stable npm release. Newer pre-releases and local builds are left in place. It then prefers the Bun-installed binary and falls back to an existing `akm` on PATH when needed. It does not run the standalone shell installers automatically.
 
 ```sh
 # macOS / Linux

package/index.ts

@@ -7,6 +7,7 @@ import { fileURLToPath } from "node:url"
 let resolvedAkmCommand = "akm"
 const autoInstallPackageRef = "akm-cli@latest"
 const moduleDir = path.dirname(fileURLToPath(import.meta.url))
+const SEMVER_PATTERN = /\b\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?\b/
 
 const AKM_AUTO_FEEDBACK = (process.env.AKM_AUTO_FEEDBACK ?? "1") !== "0"
 const AKM_AUTO_MEMORY = (process.env.AKM_AUTO_MEMORY ?? "1") !== "0"
@@ -32,6 +33,7 @@ const sessionContextEpoch = new Map<string, number>()
 const sessionContextInjectedEpoch = new Map<string, number>()
 const sessionCuratedVersion = new Map<string, number>()
 const sessionCuratedInjectedVersion = new Map<string, number>()
+type ParsedSemver = { core: [number, number, number]; prerelease: Array<string | number> | null }
 type SessionBufferEntry = {
   timestamp: string
   kind: "memory-intent" | "tool-ref"
@@ -205,6 +207,10 @@ function nowIso(): string {
   return new Date().toISOString()
 }
 
+function shouldIndexOnSessionEnd(): boolean {
+  return (process.env.AKM_INDEX_ON_SESSION_END ?? "0") === "1"
+}
+
 function buildDateTag(options?: { includeTime?: boolean }): string {
   const compactIso = new Date().toISOString().replace(/[-:]/g, "")
   return compactIso.slice(0, options?.includeTime ? CHECKPOINT_DATE_TAG_LENGTH : SESSION_DATE_TAG_LENGTH)
@@ -255,28 +261,57 @@ function runCliSyncRaw(args: string[], timeoutMs: number): { ok: true; stdout: s
   }
 }
 
-function runCurateForPrompt(text: string): string | null {
-  if (!text || text.length < AKM_CURATE_MIN_CHARS) return null
-  const result = runCliSyncRaw(
-    [
-      "--for-agent",
-      "--format",
-      "text",
-      "--detail",
-      "summary",
-      "-q",
-      "curate",
-      text,
-      "--limit",
-      String(AKM_CURATE_LIMIT),
-    ],
-    AKM_CURATE_TIMEOUT_MS,
-  )
+function appendRunScopeArgs(args: string[], sessionID: string | undefined): string[] {
+  return sessionID ? [...args, "--run", sessionID] : args
+}
+
+function runCurate(args: string[]): string | null {
+  const result = runCliSyncRaw(args, AKM_CURATE_TIMEOUT_MS)
   if (!result.ok) return null
   const body = result.stdout.trim()
   return body || null
 }
 
+function runCurateForPrompt(text: string, sessionID?: string): string | null {
+  if (!text || text.length < AKM_CURATE_MIN_CHARS) return null
+  return runCurate(
+    appendRunScopeArgs(
+      [
+        "--for-agent",
+        "--format",
+        "text",
+        "--detail",
+        "summary",
+        "-q",
+        "curate",
+        text,
+        "--limit",
+        String(AKM_CURATE_LIMIT),
+      ],
+      sessionID,
+    ),
+  )
+}
+
+function runCurateForSession(sessionID: string): string | null {
+  return runCurate(
+    appendRunScopeArgs(
+      [
+        "--for-agent",
+        "--format",
+        "text",
+        "--detail",
+        "summary",
+        "-q",
+        "curate",
+        "--limit",
+        String(AKM_CURATE_LIMIT),
+      ],
+      sessionID,
+    ),
+  )
+}
+
 function runHintsForSession(): string | null {
   const result = runCliSyncRaw(["--format", "text", "-q", "hints"], AKM_CURATE_TIMEOUT_MS)
   if (!result.ok) return null
@@ -543,6 +578,25 @@ function maybeCheckpointSessionMemory(sessionID: string): string | null {
   return captured
 }
 
+async function maybeIndexSessionMemory(
+  client: LogCapableClient,
+  sessionID: string,
+  reason: string,
+  ref: string,
+): Promise<void> {
+  if (!shouldIndexOnSessionEnd()) return
+  const result = runCliSyncRaw(["index"], AKM_CURATE_TIMEOUT_MS)
+  if (result.ok) return
+  await writePluginLog(client, "warn", "AKM session indexing failed", {
+    subsystem: "memory",
+    actor: "system",
+    sessionID,
+    reason,
+    ref,
+    error: result.error,
+  })
+}
+
 const AKM_REF_EDGE_PUNCTUATION = new Set([".", ",", ";", ":", "!", "?", "(", ")", "[", "]", "{", "}", "'", "\"", "`"])
 
 function normalizeExtractedRef(ref: string): string {
@@ -614,6 +668,41 @@ const AKM_HINTS_PREFIX = [
 
 const AKM_CURATED_HEADER = "# AKM stash — assets relevant to this prompt"
 const AKM_CURATED_TAIL = "\n\nTip: call `akm_show <ref>` to fetch full content, and record `akm_feedback <ref> positive|negative` once you know whether the asset helped."
+const AKM_CONTEXT_TRUNCATED_MARKER = "\n\n[truncated for context]"
+
+function getContextBudgetChars(): number {
+  const parsed = Number(process.env.AKM_CONTEXT_BUDGET_CHARS)
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 4000
+}
+
+function truncateContextBlock(block: string, maxChars: number): string {
+  if (block.length <= maxChars) return block
+  if (maxChars <= AKM_CONTEXT_TRUNCATED_MARKER.length) return block.slice(0, maxChars)
+  return `${block.slice(0, maxChars - AKM_CONTEXT_TRUNCATED_MARKER.length)}${AKM_CONTEXT_TRUNCATED_MARKER}`
+}
+
+function applyContextBudget(blocks: string[]): string[] {
+  const budget = getContextBudgetChars()
+  const injected: string[] = []
+  let remaining = budget
+  for (const block of blocks) {
+    if (!block) continue
+    // The host effectively concatenates injected blocks into one prompt body;
+    // we budget for a single newline separator between adjacent blocks.
+    const separatorCost = injected.length > 0 ? 1 : 0
+    if (remaining <= separatorCost) break
+    const allowed = remaining - separatorCost
+    if (block.length <= allowed) {
+      injected.push(block)
+      remaining -= separatorCost + block.length
+      continue
+    }
+    const truncated = truncateContextBlock(block, allowed)
+    if (truncated) injected.push(truncated)
+    break
+  }
+  return injected
+}
 
 // Curated quick-reference for the long-tail of `akm` CLI verbs that no longer
 // have a dedicated tool wrapper. Surfaced through akm_help so agents can
@@ -742,6 +831,72 @@ function getCommandStatus(command: string): "ok" | "missing" | "error" {
   }
 }
 
+function extractFirstSemverMatch(value: string): string | null {
+  return value.match(SEMVER_PATTERN)?.[0] ?? null
+}
+
+function getCommandVersion(command: string): string | null {
+  try {
+    const version = execFileSync(command, ["--version"], {
+      encoding: "utf8",
+      timeout: 10_000,
+    })
+    return extractFirstSemverMatch(version)
+  } catch {
+    return null
+  }
+}
+
+function parseSemver(version: string): ParsedSemver | null {
+  const normalized = extractFirstSemverMatch(version)
+  if (!normalized) return null
+
+  const [withoutBuildMetadata] = normalized.split("+", 1)
+  const [release, prereleaseText] = withoutBuildMetadata.split("-", 2)
+  const parts = release.split(".").map((part) => Number(part))
+  if (parts.length !== 3 || parts.some((part) => !Number.isInteger(part) || part < 0)) {
+    return null
+  }
+  const core = [parts[0], parts[1], parts[2]] as [number, number, number]
+
+  return {
+    core,
+    prerelease: prereleaseText
+      ? prereleaseText.split(".").map((part) => (/^\d+$/.test(part) ? Number(part) : part))
+      : null,
+  }
+}
+
+function compareSemver(left: string, right: string): number {
+  const leftParsed = parseSemver(left)
+  const rightParsed = parseSemver(right)
+  if (!leftParsed || !rightParsed) return left.localeCompare(right)
+
+  for (let index = 0; index < leftParsed.core.length; index += 1) {
+    const delta = leftParsed.core[index] - rightParsed.core[index]
+    if (delta !== 0) return delta
+  }
+
+  if (!leftParsed.prerelease && !rightParsed.prerelease) return 0
+  if (!leftParsed.prerelease) return 1
+  if (!rightParsed.prerelease) return -1
+
+  const length = Math.max(leftParsed.prerelease.length, rightParsed.prerelease.length)
+  for (let index = 0; index < length; index += 1) {
+    const leftPart = leftParsed.prerelease[index]
+    const rightPart = rightParsed.prerelease[index]
+    if (leftPart === undefined) return -1
+    if (rightPart === undefined) return 1
+    if (leftPart === rightPart) continue
+    if (typeof leftPart === "number" && typeof rightPart === "number") return leftPart - rightPart
+    if (typeof leftPart === "number") return -1
+    if (typeof rightPart === "number") return 1
+    return leftPart.localeCompare(rightPart)
+  }
+
+  return 0
+}
+
 function getBunGlobalAkmCommand(): string | null {
   try {
     const globalBin = execFileSync("bun", ["pm", "bin", "-g"], {
@@ -757,6 +912,39 @@ function getBunGlobalAkmCommand(): string | null {
   }
 }
 
+function getInstalledAkmDetails(): { command: string; version: string } | null {
+  const candidates = [resolvedAkmCommand, getBunGlobalAkmCommand(), "akm"]
+  const seen = new Set<string>()
+  for (const candidate of candidates) {
+    if (!candidate || seen.has(candidate)) continue
+    seen.add(candidate)
+    const version = getCommandVersion(candidate)
+    if (version) return { command: candidate, version }
+  }
+  return null
+}
+
+async function getLatestNpmPackageVersion(packageName: string): Promise<string | null> {
+  if (typeof fetch !== "function") return null
+
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), 10_000)
+  try {
+    const response = await fetch(`https://registry.npmjs.org/${packageName}/latest`, {
+      headers: { accept: "application/json" },
+      signal: controller.signal,
+    })
+    if (!response.ok) return null
+    const body = await response.json()
+    if (!body || typeof body !== "object") return null
+    return typeof body.version === "string" ? extractFirstSemverMatch(body.version) : null
+  } catch {
+    return null
+  } finally {
+    clearTimeout(timeout)
+  }
+}
+
 async function ensureLatestAkmInstalled(client: LogCapableClient): Promise<void> {
   try {
     execFileSync("bun", ["--version"], {
@@ -772,6 +960,39 @@ async function ensureLatestAkmInstalled(client: LogCapableClient): Promise<void>
     return
   }
 
+  const installedAkm = getInstalledAkmDetails()
+  const latestStable = await getLatestNpmPackageVersion("akm-cli")
+
+  if (installedAkm) {
+    if (!latestStable) {
+      resolvedAkmCommand = installedAkm.command
+      await writePluginLog(client, "info", "AKM auto-install skipped", {
+        subsystem: "akm",
+        installer: "bun",
+        package: autoInstallPackageRef,
+        command: resolvedAkmCommand,
+        installedVersion: installedAkm.version,
+        latestStable,
+        reason: "latest_version_unavailable",
+      })
+      return
+    }
+
+    if (compareSemver(installedAkm.version, latestStable) >= 0) {
+      resolvedAkmCommand = installedAkm.command
+      await writePluginLog(client, "info", "AKM auto-install skipped", {
+        subsystem: "akm",
+        installer: "bun",
+        package: autoInstallPackageRef,
+        command: resolvedAkmCommand,
+        installedVersion: installedAkm.version,
+        latestStable,
+        reason: "installed_version_not_older",
+      })
+      return
+    }
+  }
+
   try {
     execFileSync("bun", ["install", "-g", autoInstallPackageRef], {
       encoding: "utf8",
@@ -791,6 +1012,8 @@ async function ensureLatestAkmInstalled(client: LogCapableClient): Promise<void>
         installer: "bun",
         package: autoInstallPackageRef,
         command: resolvedAkmCommand,
+        installedVersion: installedAkm?.version ?? null,
+        latestStable,
       })
   } catch (error: unknown) {
     await writePluginLog(client, "warn", "AKM auto-install failed", {
@@ -1416,7 +1639,16 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         if (type === "session.created" || type === "session.updated") {
           if (!sid) return
           if (!sessionContextEpoch.has(sid)) sessionContextEpoch.set(sid, 0)
-          if (type === "session.created") warmIndexInBackground()
+          if (type === "session.created") {
+            warmIndexInBackground()
+            if (AKM_AUTO_CURATE && !sessionCurated.has(sid)) {
+              const curated = runCurateForSession(sid)
+              if (curated) {
+                bumpCuratedVersion(sid)
+                sessionCurated.set(sid, curated)
+              }
+            }
+          }
           if (AKM_AUTO_HINTS && !sessionHints.has(sid)) {
             const hints = runHintsForSession()
             if (hints) sessionHints.set(sid, hints)
@@ -1435,6 +1667,7 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
               reason: type,
               ref: captured,
             })
+            await maybeIndexSessionMemory(logClient, sid, type, captured)
           }
           // Drop per-session state so a re-created session does not inherit
           // stale hints/curation.
@@ -1472,6 +1705,7 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
             reason: "stop",
             ref: captured,
           })
+          await maybeIndexSessionMemory(logClient, sid, "stop", captured)
         }
       } catch {
         // Best-effort only.
@@ -1483,14 +1717,13 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         if (!sid) return
         if (!Array.isArray(output.context)) return
         markContextEpochDirty(sid)
-        const hints = sessionHints.get(sid)
-        if (hints) output.context.push(`${AKM_HINTS_PREFIX}\n\n${hints}`)
-        const curated = sessionCurated.get(sid)
-        if (curated) output.context.push(`${AKM_CURATED_HEADER}\n${curated}${AKM_CURATED_TAIL}`)
-        const workflow = sessionWorkflow.get(sid)
-        if (workflow) output.context.push(formatWorkflowContext(workflow))
-        const curatorReport = sessionCuratorReport.get(sid)
-        if (curatorReport) output.context.push(formatCuratorReportContext(curatorReport))
+        const blocks = [
+          sessionHints.get(sid) ? `${AKM_HINTS_PREFIX}\n\n${sessionHints.get(sid)}` : "",
+          sessionCurated.get(sid) ? `${AKM_CURATED_HEADER}\n${sessionCurated.get(sid)}${AKM_CURATED_TAIL}` : "",
+          sessionWorkflow.get(sid) ? formatWorkflowContext(sessionWorkflow.get(sid)!) : "",
+          sessionCuratorReport.get(sid) ? formatCuratorReportContext(sessionCuratorReport.get(sid)!) : "",
+        ]
+        output.context.push(...applyContextBudget(blocks))
       } catch {
         // Never break compaction because of plugin context.
       }
@@ -1508,19 +1741,25 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         const epoch = sessionContextEpoch.get(sid) ?? 0
         const injectedEpoch = sessionContextInjectedEpoch.get(sid)
         if (sid && injectedEpoch !== epoch) {
-          const hints = sessionHints.get(sid)
-          if (hints) output.system.push(`${AKM_HINTS_PREFIX}\n\n${hints}`)
-          const workflow = sessionWorkflow.get(sid)
-          if (workflow) output.system.push(formatWorkflowContext(workflow))
-          const curatorReport = sessionCuratorReport.get(sid)
-          if (curatorReport) output.system.push(formatCuratorReportContext(curatorReport))
+          const blocks = [
+            sessionHints.get(sid) ? `${AKM_HINTS_PREFIX}\n\n${sessionHints.get(sid)}` : "",
+            sessionCurated.get(sid) ? `${AKM_CURATED_HEADER}\n${sessionCurated.get(sid)}${AKM_CURATED_TAIL}` : "",
+            sessionWorkflow.get(sid) ? formatWorkflowContext(sessionWorkflow.get(sid)!) : "",
+            sessionCuratorReport.get(sid) ? formatCuratorReportContext(sessionCuratorReport.get(sid)!) : "",
+          ]
+          output.system.push(...applyContextBudget(blocks))
           sessionContextInjectedEpoch.set(sid, epoch)
+          if (sessionCurated.has(sid)) {
+            // Startup curation is already included in the epoch-scoped block,
+            // so mark that version as consumed to avoid a duplicate inject below.
+            sessionCuratedInjectedVersion.set(sid, sessionCuratedVersion.get(sid) ?? 0)
+          }
         }
         const curated = sid ? sessionCurated.get(sid) : undefined
         const curatedVersion = sessionCuratedVersion.get(sid) ?? 0
         if (curated) {
           if (sessionCuratedInjectedVersion.get(sid) !== curatedVersion) {
-            output.system.push(`${AKM_CURATED_HEADER}\n${curated}${AKM_CURATED_TAIL}`)
+            output.system.push(...applyContextBudget([`${AKM_CURATED_HEADER}\n${curated}${AKM_CURATED_TAIL}`]))
             sessionCuratedInjectedVersion.set(sid, curatedVersion)
           }
         }
@@ -1570,7 +1809,7 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
       // Compound-engineering loop: on every user message, curate the stash and
       // stash the result so experimental.chat.system.transform can inject it.
       if (AKM_AUTO_CURATE && input.sessionID) {
-        const curated = runCurateForPrompt(text)
+        const curated = runCurateForPrompt(text, input.sessionID)
         if (curated) {
           sessionCurated.set(input.sessionID, curated)
           bumpCuratedVersion(input.sessionID)
@@ -1771,18 +2010,8 @@ export const AkmPlugin: Plugin = async ({ client, worktree, directory }) => {
         detail: tool.schema.enum(["summary", "normal", "full"]).optional().describe("Detail level for each match. Defaults to 'summary'."),
       },
       async execute({ query, limit, detail }) {
-        const args = [
-          "--for-agent",
-          "--format",
-          "text",
-          "--detail",
-          detail ?? "summary",
-          "-q",
-          "curate",
-          query,
-          "--limit",
-          String(limit ?? 6),
-        ]
+        const args = ["curate", query, "--limit", String(limit ?? 6)]
+        if (detail) args.push("--detail", detail)
         return runCli(client as unknown as LogCapableClient, args, { toolName: "akm_curate" })
       },
     }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-opencode",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "type": "module",
   "description": "OpenCode plugin for AKM - search, show, and manage extension assets via the akm CLI, including v0.5.0 vaults, wikis, and workflows, with agentic hooks that auto-load relevant stash assets, record feedback, and harvest session memories so the stash improves every session.",
   "keywords": [