agentikit 0.0.8 → 0.0.9

package/src/stash-search.ts

@@ -7,8 +7,17 @@ import { TfIdfAdapter, type ScoredEntry } from "./similarity"
 import { buildToolInfo } from "./tool-runner"
 import { walkStash } from "./walker"
 import { makeOpenRef } from "./stash-ref"
-import type { AgentikitSearchType, SearchHit, SearchResponse } from "./stash-types"
+import type {
+  AgentikitSearchType,
+  LocalSearchHit,
+  RegistrySearchResultHit,
+  SearchHit,
+  SearchResponse,
+  SearchSource,
+  SearchUsageMode,
+} from "./stash-types"
 import { loadConfig } from "./config"
+import { searchRegistry } from "./registry-search"
 
 type IndexedAsset = {
   type: AgentikitAssetType
@@ -18,18 +27,121 @@ type IndexedAsset = {
 
 const DEFAULT_LIMIT = 20
 
+const DEFAULT_USAGE_GUIDE_BY_TYPE: Record<AgentikitAssetType, string[]> = {
+  tool: [
+    "Use the hit's runCmd for execution so runtime and working directory stay correct.",
+    "Use `akm show <openRef>` to inspect the tool before running it.",
+  ],
+  skill: [
+    "Read and apply the skill instructions as written, then adapt examples to your current repo state and task.",
+    "Use `akm show <openRef>` to read the full SKILL.md for required steps and constraints.",
+  ],
+  command: [
+    "Read the .md file, fill placeholders, and run it in the current repo context.",
+    "Use `akm show <openRef>` to retrieve the command template body.",
+  ],
+  agent: [
+    "Read the .md file and dispatch and agent using the content of the file. Use modelHint/toolPolicy when present to run the agent with compatible settings.",
+    "Use with `akm show <openRef>` to get the full prompt payload.",
+  ],
+  knowledge: [
+    "Use `akm show <openRef>` to read the document; start with `--view toc` for large files.",
+    "Use `--view section` or `--view lines` to load only the part you need.",
+  ],
+}
+
 export async function agentikitSearch(input: {
   query: string
   type?: AgentikitSearchType
   limit?: number
+  usage?: SearchUsageMode
+  source?: SearchSource
 }): Promise<SearchResponse> {
   const t0 = Date.now()
-  const query = input.query.trim().toLowerCase()
+  const query = input.query.trim()
+  const normalizedQuery = query.toLowerCase()
   const searchType = input.type ?? "any"
   const limit = normalizeLimit(input.limit)
+  const usageMode = parseSearchUsageMode(input.usage)
+  const source = parseSearchSource(input.source)
   const stashDir = resolveStashDir()
-  const config = loadConfig(stashDir)
+  const localResult = source === "registry"
+    ? undefined
+    : await searchLocal({
+      query: normalizedQuery,
+      searchType,
+      limit,
+      usageMode,
+      stashDir,
+    })
+
+  const registryResult = source === "local"
+    ? undefined
+    : await searchRegistry(query, { limit })
+
+  if (source === "local") {
+    return {
+      stashDir,
+      source,
+      hits: localResult?.hits ?? [],
+      usageGuide: localResult?.usageGuide,
+      tip: localResult?.tip,
+      timing: { totalMs: Date.now() - t0, rankMs: localResult?.rankMs, embedMs: localResult?.embedMs },
+    }
+  }
+
+  const registryHits = (registryResult?.hits ?? []).map((hit): RegistrySearchResultHit => {
+    const installRef = hit.source === "npm" ? `npm:${hit.ref}` : `github:${hit.ref}`
+    return {
+      hitSource: "registry",
+      type: "registry",
+      name: hit.title,
+      id: hit.id,
+      registrySource: hit.source,
+      ref: hit.ref,
+      description: hit.description,
+      homepage: hit.homepage,
+      score: hit.score,
+      metadata: hit.metadata,
+      installRef,
+      installCmd: `akm add ${installRef}`,
+    }
+  })
+
+  if (source === "registry") {
+    const hits = registryHits.slice(0, limit)
+    return {
+      stashDir,
+      source,
+      hits,
+      tip: hits.length === 0 ? "No matching registry entries were found." : undefined,
+      warnings: registryResult?.warnings.length ? registryResult.warnings : undefined,
+      timing: { totalMs: Date.now() - t0 },
+    }
+  }
+
+  const mergedHits = mergeSearchHits(localResult?.hits ?? [], registryHits, limit)
 
+  return {
+    stashDir,
+    source,
+    hits: mergedHits,
+    usageGuide: localResult?.usageGuide,
+    tip: mergedHits.length === 0 ? "No matching stash assets or registry entries were found." : undefined,
+    warnings: registryResult?.warnings.length ? registryResult.warnings : undefined,
+    timing: { totalMs: Date.now() - t0 },
+  }
+}
+
+async function searchLocal(input: {
+  query: string
+  searchType: AgentikitSearchType
+  limit: number
+  usageMode: SearchUsageMode
+  stashDir: string
+}): Promise<{ hits: LocalSearchHit[]; usageGuide?: Partial<Record<AgentikitAssetType, string[]>>; tip?: string; embedMs?: number; rankMs?: number }> {
+  const { query, searchType, limit, usageMode, stashDir } = input
+  const config = loadConfig(stashDir)
   const allStashDirs = [
     stashDir,
     ...config.additionalStashDirs.filter((d) => {
@@ -37,28 +149,26 @@ export async function agentikitSearch(input: {
     }),
   ]
 
-  // Try indexed search (single unified pipeline: embedding + TF-IDF as weighted features)
   const index = loadSearchIndex()
   if (index && index.entries && index.entries.length > 0 && index.stashDir === stashDir) {
-    const { hits, embedMs, rankMs } = await searchIndex(index, query, searchType, limit, stashDir, allStashDirs, config)
+    const { hits, usageGuide, embedMs, rankMs } = await searchIndex(index, query, searchType, limit, stashDir, allStashDirs, config, usageMode)
     return {
-      stashDir,
       hits,
+      usageGuide,
       tip: hits.length === 0 ? "No matching stash assets were found. Try running 'akm index' to rebuild." : undefined,
-      timing: { totalMs: Date.now() - t0, rankMs, embedMs },
+      embedMs,
+      rankMs,
     }
   }
 
-  // No index: fall back to filesystem walk + substring match across all stash dirs
   const hits = allStashDirs
     .flatMap((dir) => substringSearch(query, searchType, limit, dir))
     .slice(0, limit)
-
+  const usageGuide = shouldIncludeUsageGuide(usageMode) ? buildUsageGuide(hits.map((hit) => hit.type), searchType) : undefined
   return {
-    stashDir,
     hits,
+    usageGuide,
     tip: hits.length === 0 ? "No matching stash assets were found. Try running 'akm index' to rebuild." : undefined,
-    timing: { totalMs: Date.now() - t0 },
   }
 }
 
@@ -72,20 +182,42 @@ async function searchIndex(
   stashDir: string,
   allStashDirs: string[],
   config: import("./config").AgentikitConfig,
-): Promise<{ hits: SearchHit[]; embedMs?: number; rankMs?: number }> {
+  usageMode: SearchUsageMode,
+): Promise<{ hits: LocalSearchHit[]; usageGuide?: Partial<Record<AgentikitAssetType, string[]>>; embedMs?: number; rankMs?: number }> {
   // Filter candidates by type
   let candidates = index.entries
   if (searchType !== "any") {
     candidates = candidates.filter((ie) => ie.entry.type === searchType)
   }
 
-  if (candidates.length === 0) return { hits: [] }
+  if (candidates.length === 0) {
+    return {
+      hits: [],
+      usageGuide: shouldIncludeUsageGuide(usageMode) ? buildUsageGuide([], searchType) : undefined,
+    }
+  }
 
   // Empty query: return all entries (no scoring needed)
   if (!query) {
-    return { hits: candidates.slice(0, limit).map((ie) =>
-      buildIndexedHit({ entry: ie.entry, path: ie.path, score: 1, query, rankingMode: "tfidf", defaultStashDir: stashDir, allStashDirs }),
-    ) }
+    const selectedCandidates = candidates.slice(0, limit)
+    const hits = selectedCandidates.map((ie) =>
+      buildIndexedHit({
+        entry: ie.entry,
+        path: ie.path,
+        score: 1,
+        query,
+        rankingMode: "tfidf",
+        defaultStashDir: stashDir,
+        allStashDirs,
+        includeItemUsage: shouldIncludeItemUsage(usageMode),
+      }),
+    )
+    return {
+      hits,
+      usageGuide: shouldIncludeUsageGuide(usageMode)
+        ? buildUsageGuideFromEntries(selectedCandidates.map((candidate) => candidate.entry), searchType)
+        : undefined,
+    }
   }
 
   // Score each candidate using available signals
@@ -115,7 +247,8 @@ async function searchIndex(
   scored.sort((a, b) => b.score - a.score)
   const rankMs = Date.now() - tRank0
 
-  return { embedMs, rankMs, hits: scored.slice(0, limit).map(({ ie, score, rankingMode }) =>
+  const selected = scored.slice(0, limit)
+  const hits = selected.map(({ ie, score, rankingMode }) =>
     buildIndexedHit({
       entry: ie.entry,
       path: ie.path,
@@ -124,8 +257,18 @@ async function searchIndex(
       rankingMode,
       defaultStashDir: stashDir,
       allStashDirs,
+      includeItemUsage: shouldIncludeItemUsage(usageMode),
     }),
-  ) }
+  )
+
+  return {
+    embedMs,
+    rankMs,
+    hits,
+    usageGuide: shouldIncludeUsageGuide(usageMode)
+      ? buildUsageGuideFromEntries(selected.map((item) => item.ie.entry), searchType)
+      : undefined,
+  }
 }
 
 // ── Embedding scorer ────────────────────────────────────────────────────────
@@ -189,13 +332,13 @@ function substringSearch(
   searchType: AgentikitSearchType,
   limit: number,
   stashDir: string,
-): SearchHit[] {
+): LocalSearchHit[] {
   const assets = indexAssets(stashDir, searchType)
   return assets
     .filter((asset) => asset.name.toLowerCase().includes(query))
     .sort(compareAssets)
     .slice(0, limit)
-    .map((asset): SearchHit => assetToSearchHit(asset, stashDir))
+    .map((asset) => assetToSearchHit(asset, stashDir))
 }
 
 // ── Hit building ────────────────────────────────────────────────────────────
@@ -216,7 +359,8 @@ function buildIndexedHit(input: {
   rankingMode: "semantic" | "tfidf"
   defaultStashDir: string
   allStashDirs: string[]
-}): SearchHit {
+  includeItemUsage: boolean
+}): LocalSearchHit {
   const entryStashDir = findStashDirForPath(input.path, input.allStashDirs) ?? input.defaultStashDir
   const typeRoot = path.join(entryStashDir, TYPE_DIRS[input.entry.type])
   const openRefName = deriveCanonicalAssetName(input.entry.type, typeRoot, input.path)
@@ -228,7 +372,8 @@ function buildIndexedHit(input: {
 
   const whyMatched = buildWhyMatched(input.entry, input.query, input.rankingMode, qualityBoost, confidenceBoost)
 
-  const hit: SearchHit = {
+  const hit: LocalSearchHit = {
+    hitSource: "local",
     type: input.entry.type,
     name: input.entry.name,
     path: input.path,
@@ -239,6 +384,10 @@ function buildIndexedHit(input: {
     whyMatched,
   }
 
+  if (input.includeItemUsage && input.entry.usage && input.entry.usage.length > 0) {
+    hit.usage = input.entry.usage
+  }
+
   if (input.entry.type === "tool") {
     try {
       const toolInfo = buildToolInfo(entryStashDir, input.path)
@@ -288,9 +437,10 @@ function toScoredEntries(entries: IndexedEntry[]): ScoredEntry[] {
   }))
 }
 
-function assetToSearchHit(asset: IndexedAsset, stashDir: string): SearchHit {
+function assetToSearchHit(asset: IndexedAsset, stashDir: string): LocalSearchHit {
   if (asset.type !== "tool") {
     return {
+      hitSource: "local",
       type: asset.type,
       name: asset.name,
       path: asset.path,
@@ -299,6 +449,7 @@ function assetToSearchHit(asset: IndexedAsset, stashDir: string): SearchHit {
   }
   const toolInfo = buildToolInfo(stashDir, asset.path)
   return {
+    hitSource: "local",
     type: "tool",
     name: asset.name,
     path: asset.path,
@@ -315,6 +466,107 @@ function normalizeLimit(limit?: number): number {
   return Math.min(Math.floor(limit), 200)
 }
 
+function parseSearchUsageMode(mode: SearchUsageMode | undefined): SearchUsageMode {
+  if (mode === "none" || mode === "both" || mode === "item" || mode === "guide") {
+    return mode
+  }
+  if (typeof mode === "undefined") return "both"
+  throw new Error(`Invalid usage mode: ${String(mode)}. Expected one of: none|both|item|guide`)
+}
+
+function parseSearchSource(source: SearchSource | undefined): SearchSource {
+  if (source === "local" || source === "registry" || source === "both") return source
+  if (typeof source === "undefined") return "local"
+  throw new Error(`Invalid search source: ${String(source)}. Expected one of: local|registry|both`)
+}
+
+function mergeSearchHits(localHits: LocalSearchHit[], registryHits: RegistrySearchResultHit[], limit: number): SearchHit[] {
+  const merged: SearchHit[] = []
+  let localIndex = 0
+  let registryIndex = 0
+
+  while (merged.length < limit && (localIndex < localHits.length || registryIndex < registryHits.length)) {
+    if (localIndex < localHits.length) {
+      merged.push(localHits[localIndex])
+      localIndex += 1
+      if (merged.length >= limit) break
+    }
+    if (registryIndex < registryHits.length) {
+      merged.push(registryHits[registryIndex])
+      registryIndex += 1
+    }
+  }
+
+  return merged
+}
+
+function shouldIncludeUsageGuide(mode: SearchUsageMode): boolean {
+  return mode === "both" || mode === "guide"
+}
+
+function shouldIncludeItemUsage(mode: SearchUsageMode): boolean {
+  return mode === "both" || mode === "item"
+}
+
+function buildUsageGuideFromEntries(
+  entries: IndexedEntry["entry"][],
+  searchType: AgentikitSearchType,
+): Partial<Record<AgentikitAssetType, string[]>> | undefined {
+  const types = entries.map((entry) => entry.type)
+  const fallbackGuide = buildUsageGuide(types, searchType)
+  const metadataByType = new Map<AgentikitAssetType, string[]>()
+
+  for (const entry of entries) {
+    if (!entry.usage || entry.usage.length === 0) continue
+    const current = metadataByType.get(entry.type) ?? []
+    for (const item of entry.usage) {
+      const trimmed = item.trim()
+      if (trimmed && !current.includes(trimmed)) current.push(trimmed)
+    }
+    if (current.length > 0) metadataByType.set(entry.type, current)
+  }
+
+  if (!fallbackGuide && metadataByType.size === 0) return undefined
+
+  const result: Partial<Record<AgentikitAssetType, string[]>> = {}
+  for (const assetType of resolveGuideTypes(types, searchType)) {
+    const lines: string[] = []
+    const metadataLines = metadataByType.get(assetType)
+    if (metadataLines && metadataLines.length > 0) {
+      lines.push(...metadataLines)
+    }
+    const fallbackLines = fallbackGuide?.[assetType]
+    if (fallbackLines && fallbackLines.length > 0) {
+      for (const line of fallbackLines) {
+        if (!lines.includes(line)) lines.push(line)
+      }
+    }
+    if (lines.length > 0) result[assetType] = lines
+  }
+
+  return Object.keys(result).length > 0 ? result : undefined
+}
+
+function buildUsageGuide(
+  hitTypes: AgentikitAssetType[],
+  searchType: AgentikitSearchType,
+): Partial<Record<AgentikitAssetType, string[]>> | undefined {
+  const result: Partial<Record<AgentikitAssetType, string[]>> = {}
+  for (const assetType of resolveGuideTypes(hitTypes, searchType)) {
+    result[assetType] = usageGuideByType(assetType)
+  }
+  return Object.keys(result).length > 0 ? result : undefined
+}
+
+function resolveGuideTypes(hitTypes: AgentikitAssetType[], searchType: AgentikitSearchType): AgentikitAssetType[] {
+  if (searchType !== "any") return [searchType]
+  return Array.from(new Set(hitTypes))
+}
+
+function usageGuideByType(type: AgentikitAssetType): string[] {
+  return DEFAULT_USAGE_GUIDE_BY_TYPE[type]
+}
+
 function fileToAsset(assetType: AgentikitAssetType, root: string, file: string): IndexedAsset | undefined {
   const name = deriveCanonicalAssetName(assetType, root, file)
   if (!name) return undefined

package/src/stash-show.ts

@@ -60,7 +60,8 @@ export function agentikitShow(input: { ref: string; view?: KnowledgeView }): Sho
         name: parsed.name,
         path: assetPath,
         description: toStringOrUndefined(parsedMd.data.description),
-        prompt: parsedMd.content,
+        prompt: "Dispatching prompt must include the agent's full prompt content verbatim; summaries are non-compliant. \n\n" 
+        + parsedMd.content,
         toolPolicy: parsedMd.data.tools,
         modelHint: parsedMd.data.model,
       }
@@ -89,7 +90,14 @@ export function agentikitShow(input: { ref: string; view?: KnowledgeView }): Sho
         }
         case "section": {
           const section = extractSection(content, v.heading)
-          if (!section) throw new Error(`Section "${v.heading}" not found in ${parsed.name}`)
+          if (!section) {
+            return {
+              type: "knowledge",
+              name: parsed.name,
+              path: assetPath,
+              content: `Section "${v.heading}" not found in ${parsed.name}. Try --view toc to discover available headings.`,
+            }
+          }
           return { type: "knowledge", name: parsed.name, path: assetPath, content: section.content }
         }
         case "lines": {

package/src/stash-types.ts

@@ -1,9 +1,13 @@
 import type { AgentikitAssetType } from "./common"
+import type { RegistrySource } from "./registry-types"
 import type { ToolKind } from "./tool-runner"
 
 export type AgentikitSearchType = AgentikitAssetType | "any"
+export type SearchUsageMode = "none" | "both" | "item" | "guide"
+export type SearchSource = "local" | "registry" | "both"
 
-export interface SearchHit {
+export interface LocalSearchHit {
+  hitSource: "local"
   type: AgentikitAssetType
   name: string
   path: string
@@ -14,16 +18,187 @@ export interface SearchHit {
   whyMatched?: string[]
   runCmd?: string
   kind?: ToolKind
+  usage?: string[]
 }
 
+export interface RegistrySearchResultHit {
+  hitSource: "registry"
+  type: "registry"
+  name: string
+  path?: string
+  openRef?: string
+  id: string
+  registrySource: RegistrySource
+  ref: string
+  description?: string
+  tags?: string[]
+  homepage?: string
+  score?: number
+  whyMatched?: string[]
+  runCmd?: string
+  kind?: ToolKind
+  usage?: string[]
+  metadata?: Record<string, string>
+  installRef: string
+  installCmd: string
+}
+
+export type SearchHit = LocalSearchHit | RegistrySearchResultHit
+
 export interface SearchResponse {
   stashDir: string
+  source: SearchSource
   hits: SearchHit[]
+  usageGuide?: Partial<Record<AgentikitAssetType, string[]>>
   tip?: string
+  warnings?: string[]
   /** Timing counters in milliseconds */
   timing?: { totalMs: number; rankMs?: number; embedMs?: number }
 }
 
+export interface AddResponse {
+  stashDir: string
+  ref: string
+  installed: {
+    id: string
+    source: RegistrySource
+    ref: string
+    artifactUrl: string
+    resolvedVersion?: string
+    resolvedRevision?: string
+    stashRoot: string
+    cacheDir: string
+    extractedDir: string
+    installedAt: string
+  }
+  config: {
+    additionalStashDirs: string[]
+    installedRegistryCount: number
+  }
+  index: {
+    mode: "full" | "incremental"
+    totalEntries: number
+    directoriesScanned: number
+    directoriesSkipped: number
+  }
+}
+
+export interface RegistryInstallStatus {
+  id: string
+  source: RegistrySource
+  ref: string
+  artifactUrl: string
+  resolvedVersion?: string
+  resolvedRevision?: string
+  stashRoot: string
+  cacheDir: string
+  extractedDir: string
+  installedAt: string
+}
+
+export interface RegistryListEntry {
+  id: string
+  source: RegistrySource
+  ref: string
+  artifactUrl: string
+  resolvedVersion?: string
+  resolvedRevision?: string
+  stashRoot: string
+  cacheDir: string
+  installedAt: string
+  status: {
+    cacheDirExists: boolean
+    stashRootExists: boolean
+  }
+}
+
+export interface ListResponse {
+  stashDir: string
+  installed: RegistryListEntry[]
+  totalInstalled: number
+}
+
+export interface RemoveResponse {
+  stashDir: string
+  target: string
+  removed: {
+    id: string
+    source: RegistrySource
+    ref: string
+    cacheDir: string
+    stashRoot: string
+  }
+  config: {
+    additionalStashDirs: string[]
+    installedRegistryCount: number
+  }
+  index: {
+    mode: "full" | "incremental"
+    totalEntries: number
+    directoriesScanned: number
+    directoriesSkipped: number
+  }
+}
+
+export interface ReinstallResultItem {
+  id: string
+  source: RegistrySource
+  ref: string
+  previousCacheDir: string
+  installed: RegistryInstallStatus
+}
+
+export interface ReinstallResponse {
+  stashDir: string
+  target?: string
+  all: boolean
+  processed: ReinstallResultItem[]
+  config: {
+    additionalStashDirs: string[]
+    installedRegistryCount: number
+  }
+  index: {
+    mode: "full" | "incremental"
+    totalEntries: number
+    directoriesScanned: number
+    directoriesSkipped: number
+  }
+}
+
+export interface UpdateResultItem {
+  id: string
+  source: RegistrySource
+  ref: string
+  previous: {
+    resolvedVersion?: string
+    resolvedRevision?: string
+    cacheDir: string
+  }
+  installed: RegistryInstallStatus
+  changed: {
+    version: boolean
+    revision: boolean
+    any: boolean
+  }
+}
+
+export interface UpdateResponse {
+  stashDir: string
+  target?: string
+  all: boolean
+  processed: UpdateResultItem[]
+  config: {
+    additionalStashDirs: string[]
+    installedRegistryCount: number
+  }
+  index: {
+    mode: "full" | "incremental"
+    totalEntries: number
+    directoriesScanned: number
+    directoriesSkipped: number
+  }
+}
+
 export interface ShowResponse {
   type: AgentikitAssetType
   name: string

package/src/stash.ts

@@ -6,11 +6,26 @@ export type { ToolKind } from "./tool-runner"
 
 export { agentikitSearch } from "./stash-search"
 export { agentikitShow } from "./stash-show"
+export { agentikitAdd } from "./stash-add"
+export { agentikitList, agentikitRemove, agentikitReinstall, agentikitUpdate } from "./stash-registry"
 
 export type {
+  AddResponse,
   AgentikitSearchType,
+  LocalSearchHit,
+  RegistrySearchResultHit,
+  SearchSource,
+  SearchUsageMode,
   SearchHit,
   SearchResponse,
   ShowResponse,
   KnowledgeView,
+  ListResponse,
+  RemoveResponse,
+  ReinstallResponse,
+  UpdateResponse,
+  RegistryListEntry,
+  RegistryInstallStatus,
+  ReinstallResultItem,
+  UpdateResultItem,
 } from "./stash-types"