akm-opencode 0.9.202808211043 → 0.9.11202609031834

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-opencode",
-  "version": "0.9.202808211043",
+  "version": "0.9.11202609031834",
   "type": "module",
   "description": "OpenCode plugin for AKM 0.9 with in-process search, show, and curate tools plus feedback and remember.",
   "keywords": [
@@ -39,7 +39,7 @@
   },
   "dependencies": {
     "@opencode-ai/plugin": "^1.18.14",
-    "akm-cli": "^0.9.0"
+    "akm-cli": "^0.9.8"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",

package/shared/akm-version.ts

@@ -13,28 +13,56 @@
 // same code path runs on both sides.
 //
 // A single caret clause anchored at the stable release covers the whole
-// supported line: `^0.9.0` admits every stable 0.9.x (0.9.0, 0.9.3, ...).
-// The pre-release floor (`^0.9.0-rc.14`) was retired when akm-cli 0.9.0
-// stable shipped: release candidates are dead once the release exists, and
-// keeping the RC floor would have kept recommending a prerelease install ref.
+// supported line: `^0.9.8` admits stable 0.9.8 and later 0.9.x releases.
+// 0.9.8 is the compatibility floor, and the reason is a one-way one: 0.9.8
+// adds state migrations 025 and 026, so once any 0.9.8 command opens
+// `state.db` an older CLI refuses to open it at all. A home these plugins
+// have driven is therefore a 0.9.8+ home, and admitting 0.9.7 would point
+// the gate at a CLI that cannot read it. Its ref grammar, progressive-search
+// metadata, token-budgeted curate packing, workflow lifecycle, and
+// task/workflow wire contracts are the ones these plugins implement.
 //
-// KNOWN GAP: NO prerelease satisfies this range — not 0.9.0-rc.15, and not a
-// *future* line such as 0.9.1-rc.1. That is node-semver's documented behavior
+// KNOWN GAP: NO prerelease satisfies this range — not 0.9.8-rc.1, and not a
+// *future* line such as 0.9.9-rc.1. That is node-semver's documented behavior
 // and the vendored matcher reproduces it: a prerelease only satisfies a range
 // whose lower bound is a prerelease with the same major.minor.patch. Admitting
 // a prerelease line again is an explicit one-clause edit here
-// (`^0.9.0 || ^0.9.1-rc.1`) when such a build actually needs testing — a
+// (`^0.9.8 || ^0.9.9-rc.1`) when such a build actually needs testing — a
 // deliberate opt-in rather than a range that silently accepts untested
 // prereleases.
 //
-// 0.8.0 support was dropped for the 0.9.0 release: 0.9.0-only runtime paths
-// (`akm proposal extract --session-id`, curate `--detail brief`) fail against
-// 0.8.x, so accepting 0.8.x here would silently pass the version gate onto a
-// CLI the plugin no longer fully works with.
+// Earlier 0.9 releases are deliberately excluded as well: accepting them
+// would silently pass the version gate onto a CLI with retired ref and
+// workflow contracts, or one that cannot open a migrated state.db.
+//
+// #106 asked, as a maintainer decision, whether a caret range is the right
+// matcher at all given akm's own STABILITY.md: "0.9.x patch releases may
+// also contain breaking changes" while the 0.9.x line pays off technical
+// debt pre-1.0. Verified against that document and against the akm 0.9.12
+// branch (itlackey/akm, release/0.9.12) while checking this plugin for
+// compatibility: every akm surface these plugins call is tier Stable
+// (search, curate, show, info, feedback, workflow list) EXCEPT `akm proposal
+// extract`, which is tier Evolving — "payload shapes may shift" — and is
+// exactly the surface `extractSession()`/`lastExtractFailureWarning()` parse
+// most deeply. 0.9.12 did change that envelope again (added `engine`,
+// `engineKind`, `skipReasons`, and an aggregate `warnings[]` line for an
+// all-skip run — see akm#912/#913) — the Evolving tag is not decorative.
+// Decision: keep the caret range, not because the risk is unreal but because
+// a narrower pin doesn't address it — the failure mode #106 reported was
+// never "the version gate passed when it shouldn't have" (an *already
+// installed* plugin at 0.9.1 would need 0.9.1 itself to have shipped a
+// tighter range, which a future release cannot retroactively fix), it was
+// "a breaking change degraded to silence downstream of the gate". That is
+// what #107/#108/#109 fix directly: every read of the extract envelope goes
+// through safeJsonParse with every field optional-chained, so an Evolving
+// surface changing shape degrades to "say less" (a missing field silently
+// omitted) rather than a crash or a fabricated warning. That is the
+// appropriate mitigation for an Evolving dependency the gate cannot pin
+// away without also rejecting users on every newer patch release.
 
 import { satisfies } from "./vendor-semver"
 
-export const AKM_VERSION_RANGE = "^0.9.0"
+export const AKM_VERSION_RANGE = "^0.9.8"
 
 /**
  * True when `version` is a valid semver string that satisfies

package/shared/curate-render.ts

@@ -0,0 +1,108 @@
+/**
+ * #110 — client-side filtering and rendering for `akm curate`'s `--format
+ * json` response, used only by the opt-in relevance-floor path
+ * (AKM_CURATE_MIN_SCORE) in both hooks.
+ *
+ * Why this exists: `akm curate --format text` (the default the hooks have
+ * always used) never prints a per-item relevance score — `formatCuratePlain`
+ * on the CLI side has no `score` line — so the hooks had no way to tell "five
+ * weak hits" from "five strong hits" and always emitted whatever the CLI
+ * returned. `--shape agent` DOES carry `score` (and `type`) on each item in
+ * `--format json`, so the fix lives here: switch to JSON, decide, and render
+ * just enough text to stay useful — NOT a full port of the CLI's own
+ * formatter (next-steps footer, warnings block, etc. — the hooks already
+ * append their own tip line and provenance banner around this).
+ *
+ * This module is intentionally not wired into the default (score-floor
+ * disabled) code path: that path keeps calling `--format text` exactly as
+ * before, so existing behavior — and every test that fakes the CLI's text
+ * output — is untouched. See akm-plugins#110 for the fuller design tradeoff
+ * (a renderer that fully replaces `--format text` in all cases, so
+ * type-priority ranking could apply unconditionally rather than only when
+ * the floor is enabled, was considered and deferred as a larger, riskier
+ * change than this issue's evidence justified doing in one pass).
+ */
+
+export interface CuratedItem {
+  type?: unknown
+  name?: unknown
+  ref?: unknown
+  description?: unknown
+  reason?: unknown
+  score?: unknown
+}
+
+// Asset types a human or agent authored directly for THIS stash, as opposed
+// to a bulk-imported snapshot of external content (a website crawl, a wiki
+// page, a transcript). #110's evidence: on a real machine, a GitHub Copilot
+// blog post and three doc-site snapshots outranked same-day lessons and
+// memories written about the exact subject being asked about. This is a
+// preference, not a filter — imported types still show, just after authored
+// ones — because a snapshot can still be the best (or only) available hit.
+const AUTHORED_ASSET_TYPES = new Set([
+  "lesson",
+  "memory",
+  "knowledge",
+  "skill",
+  "command",
+  "agent",
+  "instruction",
+  "fact",
+  "workflow",
+  "task",
+  "env",
+  "secret",
+])
+
+function isAuthoredType(type: unknown): boolean {
+  return typeof type === "string" && AUTHORED_ASSET_TYPES.has(type)
+}
+
+/**
+ * Keep items scoring at or above `minScore`, then stable-sort authored asset
+ * types ahead of imported/scraped ones. Items with no numeric `score` are
+ * kept regardless of `minScore` — a missing score is not evidence the item is
+ * weak, it means this response shape did not carry one, and inventing a
+ * reason to drop it would repeat the mistake #107 fixed on the extract side
+ * (a specific wrong guess is worse than none).
+ *
+ * akm-cli has already decided which N items are the top-N for this query;
+ * this only decides which of those N are worth showing, and in what order —
+ * it never asks the CLI for more candidates to backfill a dropped slot, so a
+ * strict floor can legitimately shrink the result set to nothing.
+ */
+export function filterAndRankCuratedItems(rawItems: unknown, minScore: number): CuratedItem[] {
+  if (!Array.isArray(rawItems)) return []
+  const items = rawItems.filter((item): item is CuratedItem => !!item && typeof item === "object")
+  const survivors =
+    minScore > 0 ? items.filter((item) => typeof item.score !== "number" || item.score >= minScore) : items
+  return survivors
+    .map((item, index) => ({ item, index }))
+    .sort((a, b) => {
+      const rankDiff = Number(isAuthoredType(b.item.type)) - Number(isAuthoredType(a.item.type))
+      // Stable within each group: preserve akm-cli's own relative order
+      // (its score-based ranking) rather than re-sorting by score here too.
+      return rankDiff !== 0 ? rankDiff : a.index - b.index
+    })
+    .map(({ item }) => item)
+}
+
+/**
+ * Compact plain-text rendering of already-filtered/ranked items. Deliberately
+ * smaller than the CLI's own `formatCuratePlain`: no "Next steps" footer or
+ * warnings block, because both hooks that call this already append their own
+ * tip line (CURATED_CONTEXT_TAIL) and provenance banner around the result.
+ */
+export function renderCuratedItems(query: string, items: readonly CuratedItem[]): string {
+  const lines: string[] = [`Curated results for "${query}"`]
+  for (const item of items) {
+    const type = typeof item.type === "string" ? item.type : "unknown"
+    const name = typeof item.name === "string" ? item.name : "unnamed"
+    lines.push("")
+    lines.push(`[${type}] ${name}`)
+    if (typeof item.description === "string" && item.description) lines.push(`  ${item.description}`)
+    if (typeof item.ref === "string" && item.ref) lines.push(`  ref: ${item.ref}`)
+    if (typeof item.reason === "string" && item.reason) lines.push(`  why: ${item.reason}`)
+  }
+  return lines.join("\n")
+}

package/shared/memory-events.ts

@@ -25,6 +25,10 @@ export type AkmMemoryEventType =
   | "subagent_started"
   | "post_compact_summary"
   | "feedback_recorded"
+  // The opencode write gate (#99) emits exactly one of these per watched
+  // write-tool invocation, with a named reason in `input.reason`. One name, not
+  // two: fire and skip are the same event with different outcome.status.
+  | "write_gate"
 
 export type AkmMemoryEvent = {
   version: 1

package/shared/recall-policy.ts

@@ -20,7 +20,7 @@ export type RecallDecision = {
   scopeHints?: string[]
 }
 
-const REF_RE = /(?:skill|command|agent|knowledge|workflow|lesson|wiki|memory|env|secret):[A-Za-z0-9._/-]+/i
+import { extractAkmRefsFromString } from "./ref-extraction"
 
 export function shouldRecall(prompt: string, options?: { activeWorkflow?: boolean; recentAssetFailure?: boolean }): RecallDecision {
   const text = prompt.trim()
@@ -35,7 +35,11 @@ export function shouldRecall(prompt: string, options?: { activeWorkflow?: boolea
   if (/\b(hi|hello|how are you|good morning|good night)\b/i.test(lower) && text.length < 40) {
     return { shouldRecall: false, reason: "skip-chitchat", query: text, scopeHints }
   }
-  if (/\bakm\b|\bstash\b/.test(lower) || REF_RE.test(text)) {
+  // Reuse the resolver-facing parser rather than carrying a second, stale
+  // grammar here. AKM 0.9.7 refs are [bundle//]conceptId[#fragment]; retired
+  // type:name strings must not turn an otherwise low-signal prompt into an
+  // explicit AKM recall.
+  if (/\bakm\b|\bbundle\b/.test(lower) || extractAkmRefsFromString(text).length > 0) {
     return { shouldRecall: true, reason: "explicit-akm", query: text, scopeHints: ["akm"] }
   }
   if (/\b(remember|memory|prior session|previous decision)\b/.test(lower)) {
@@ -47,7 +51,7 @@ export function shouldRecall(prompt: string, options?: { activeWorkflow?: boolea
   if (/\b(dispatch|agent|subagent|reviewer|planner|curator)\b/.test(lower)) {
     return { shouldRecall: true, reason: "agent-dispatch", query: text, scopeHints: ["agent"] }
   }
-  if (/\b(command|slash command|run the stash command)\b/.test(lower)) {
+  if (/\b(command|slash command|run the bundle command)\b/.test(lower)) {
     return { shouldRecall: true, reason: "command-dispatch", query: text, scopeHints: ["command"] }
   }
   if (/\b(wiki|docs|knowledge base|ingest|lint)\b/.test(lower)) {