akm-opencode 0.5.2 → 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. |

package/index.ts

@@ -207,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)
@@ -257,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
@@ -545,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 {
@@ -616,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
@@ -1552,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)
@@ -1571,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.
@@ -1608,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.
@@ -1619,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.
       }
@@ -1644,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)
           }
         }
@@ -1706,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)
@@ -1907,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.2",
+  "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": [