agentikit 0.0.9 → 0.0.13

package/src/embedder.ts

@@ -1,4 +1,5 @@
 import type { EmbeddingConnectionConfig } from "./config"
+import { fetchWithTimeout } from "./common"
 
 // ── Types ───────────────────────────────────────────────────────────────────
 
@@ -6,22 +7,27 @@ export type EmbeddingVector = number[]
 
 // ── Singleton local embedder ────────────────────────────────────────────────
 
-let localEmbedder: any
+interface TransformerPipeline {
+  (text: string, options: { pooling: string; normalize: boolean }): Promise<{ data: Float32Array }>
+}
+
+let localEmbedder: TransformerPipeline | undefined
 
-async function getLocalEmbedder(): Promise<any> {
+async function getLocalEmbedder(): Promise<TransformerPipeline> {
   if (!localEmbedder) {
-    let pipeline: any
+    let pipeline: unknown
     try {
       const mod = await import("@xenova/transformers")
-      pipeline = mod.pipeline
+      pipeline = mod.pipeline as unknown
     } catch {
       throw new Error(
         "Semantic search requires @xenova/transformers. Install it with: npm install @xenova/transformers",
       )
     }
-    localEmbedder = await pipeline("feature-extraction", "Xenova/all-MiniLM-L6-v2")
+    const pipelineFn = pipeline as (task: string, model: string) => Promise<TransformerPipeline>
+    localEmbedder = await pipelineFn("feature-extraction", "Xenova/all-MiniLM-L6-v2")
   }
-  return localEmbedder
+  return localEmbedder!
 }
 
 async function embedLocal(text: string): Promise<EmbeddingVector> {
@@ -41,13 +47,18 @@ async function embedRemote(
     headers["Authorization"] = `Bearer ${config.apiKey}`
   }
 
-  const response = await fetch(config.endpoint, {
+  const body: { input: string; model: string; dimensions?: number } = {
+    input: text,
+    model: config.model,
+  }
+  if (config.dimension) {
+    body.dimensions = config.dimension
+  }
+
+  const response = await fetchWithTimeout(config.endpoint, {
     method: "POST",
     headers,
-    body: JSON.stringify({
-      input: text,
-      model: config.model,
-    }),
+    body: JSON.stringify(body),
   })
 
   if (!response.ok) {

package/src/github.ts

@@ -0,0 +1,21 @@
+export const GITHUB_API_BASE = "https://api.github.com"
+
+export function githubHeaders(): HeadersInit {
+  const token = process.env.GITHUB_TOKEN?.trim()
+  const headers: Record<string, string> = {
+    Accept: "application/vnd.github+json",
+    "User-Agent": "agentikit-registry",
+  }
+  if (token) headers.Authorization = `Bearer ${token}`
+  return headers
+}
+
+export function asRecord(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : {}
+}
+
+export function asString(value: unknown): string | undefined {
+  return typeof value === "string" && value ? value : undefined
+}

package/src/handlers/agent-handler.ts

@@ -0,0 +1,32 @@
+import { parseFrontmatter, toStringOrUndefined } from "../frontmatter"
+import { isMarkdownFile, markdownCanonicalName, markdownAssetPath } from "./markdown-helpers"
+import type { AssetTypeHandler, ShowInput } from "../asset-type-handler"
+import type { ShowResponse } from "../stash-types"
+
+export const agentHandler: AssetTypeHandler = {
+  typeName: "agent",
+  stashDir: "agents",
+
+  isRelevantFile: isMarkdownFile,
+  toCanonicalName: markdownCanonicalName,
+  toAssetPath: markdownAssetPath,
+
+  buildShowResponse(input: ShowInput): ShowResponse {
+    const parsedMd = parseFrontmatter(input.content)
+    return {
+      type: "agent",
+      name: input.name,
+      path: input.path,
+      description: toStringOrUndefined(parsedMd.data.description),
+      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,
+    }
+  },
+
+  defaultUsageGuide: [
+    "Read the .md file and dispatch an 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.",
+  ],
+}

package/src/handlers/command-handler.ts

@@ -0,0 +1,29 @@
+import { parseFrontmatter, toStringOrUndefined } from "../frontmatter"
+import { isMarkdownFile, markdownCanonicalName, markdownAssetPath } from "./markdown-helpers"
+import type { AssetTypeHandler, ShowInput } from "../asset-type-handler"
+import type { ShowResponse } from "../stash-types"
+
+export const commandHandler: AssetTypeHandler = {
+  typeName: "command",
+  stashDir: "commands",
+
+  isRelevantFile: isMarkdownFile,
+  toCanonicalName: markdownCanonicalName,
+  toAssetPath: markdownAssetPath,
+
+  buildShowResponse(input: ShowInput): ShowResponse {
+    const parsedMd = parseFrontmatter(input.content)
+    return {
+      type: "command",
+      name: input.name,
+      path: input.path,
+      description: toStringOrUndefined(parsedMd.data.description),
+      template: parsedMd.content,
+    }
+  },
+
+  defaultUsageGuide: [
+    "Read the .md file, fill placeholders, and run it in the current repo context.",
+    "Use `akm show <openRef>` to retrieve the command template body.",
+  ],
+}

package/src/handlers/index.ts

@@ -0,0 +1,25 @@
+import { registerAssetType } from "../asset-type-handler"
+import { toolHandler } from "./tool-handler"
+import { skillHandler } from "./skill-handler"
+import { commandHandler } from "./command-handler"
+import { agentHandler } from "./agent-handler"
+import { knowledgeHandler } from "./knowledge-handler"
+import { scriptHandler } from "./script-handler"
+
+/**
+ * Register all built-in asset type handlers.
+ * This must be called (imported) before any handler lookups.
+ */
+registerAssetType(toolHandler)
+registerAssetType(skillHandler)
+registerAssetType(commandHandler)
+registerAssetType(agentHandler)
+registerAssetType(knowledgeHandler)
+registerAssetType(scriptHandler)
+
+export { toolHandler } from "./tool-handler"
+export { skillHandler } from "./skill-handler"
+export { commandHandler } from "./command-handler"
+export { agentHandler } from "./agent-handler"
+export { knowledgeHandler } from "./knowledge-handler"
+export { scriptHandler } from "./script-handler"

package/src/handlers/knowledge-handler.ts

@@ -0,0 +1,62 @@
+import fs from "node:fs"
+import { parseMarkdownToc, extractSection, extractLineRange, extractFrontmatterOnly, formatToc } from "../markdown"
+import { isMarkdownFile, markdownCanonicalName, markdownAssetPath } from "./markdown-helpers"
+import type { AssetTypeHandler, ShowInput } from "../asset-type-handler"
+import type { ShowResponse } from "../stash-types"
+import type { StashEntry } from "../metadata"
+
+export const knowledgeHandler: AssetTypeHandler = {
+  typeName: "knowledge",
+  stashDir: "knowledge",
+
+  isRelevantFile: isMarkdownFile,
+  toCanonicalName: markdownCanonicalName,
+  toAssetPath: markdownAssetPath,
+
+  buildShowResponse(input: ShowInput): ShowResponse {
+    const v = input.view ?? { mode: "full" }
+    switch (v.mode) {
+      case "toc": {
+        const toc = parseMarkdownToc(input.content)
+        return { type: "knowledge", name: input.name, path: input.path, content: formatToc(toc) }
+      }
+      case "frontmatter": {
+        const fm = extractFrontmatterOnly(input.content)
+        return { type: "knowledge", name: input.name, path: input.path, content: fm ?? "(no frontmatter)" }
+      }
+      case "section": {
+        const section = extractSection(input.content, v.heading)
+        if (!section) {
+          return {
+            type: "knowledge",
+            name: input.name,
+            path: input.path,
+            content: `Section "${v.heading}" not found in ${input.name}. Try --view toc to discover available headings.`,
+          }
+        }
+        return { type: "knowledge", name: input.name, path: input.path, content: section.content }
+      }
+      case "lines": {
+        return { type: "knowledge", name: input.name, path: input.path, content: extractLineRange(input.content, v.start, v.end) }
+      }
+      default: {
+        return { type: "knowledge", name: input.name, path: input.path, content: input.content }
+      }
+    }
+  },
+
+  defaultUsageGuide: [
+    "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.",
+  ],
+
+  extractTypeMetadata(entry: StashEntry, file: string): void {
+    try {
+      const mdContent = fs.readFileSync(file, "utf8")
+      const toc = parseMarkdownToc(mdContent)
+      if (toc.headings.length > 0) entry.toc = toc.headings
+    } catch {
+      // Non-fatal: skip TOC if file can't be read
+    }
+  },
+}

package/src/handlers/markdown-helpers.ts

@@ -0,0 +1,19 @@
+import path from "node:path"
+import { toPosix } from "../common"
+
+/**
+ * Shared file-system helpers for markdown-based asset types
+ * (command, agent, knowledge).
+ */
+
+export function isMarkdownFile(fileName: string): boolean {
+  return path.extname(fileName).toLowerCase() === ".md"
+}
+
+export function markdownCanonicalName(typeRoot: string, filePath: string): string | undefined {
+  return toPosix(path.relative(typeRoot, filePath))
+}
+
+export function markdownAssetPath(typeRoot: string, name: string): string {
+  return path.join(typeRoot, name)
+}

package/src/handlers/script-handler.ts

@@ -0,0 +1,92 @@
+import path from "node:path"
+import { SCRIPT_EXTENSIONS, SCRIPT_EXTENSIONS_BROAD } from "../asset-spec"
+import { hasErrnoCode, toPosix } from "../common"
+import { buildToolInfo } from "../tool-runner"
+import { extractDescriptionFromComments } from "../metadata"
+import type { AssetTypeHandler, ShowInput } from "../asset-type-handler"
+import type { ShowResponse, LocalSearchHit } from "../stash-types"
+import type { StashEntry } from "../metadata"
+
+/** Extensions that buildToolInfo can handle (tool-runner supported) */
+const RUNNABLE_EXTENSIONS = SCRIPT_EXTENSIONS
+
+export const scriptHandler: AssetTypeHandler = {
+  typeName: "script",
+  stashDir: "scripts",
+
+  isRelevantFile(fileName: string): boolean {
+    return SCRIPT_EXTENSIONS_BROAD.has(path.extname(fileName).toLowerCase())
+  },
+
+  toCanonicalName(typeRoot: string, filePath: string): string | undefined {
+    return toPosix(path.relative(typeRoot, filePath))
+  },
+
+  toAssetPath(typeRoot: string, name: string): string {
+    return path.join(typeRoot, name)
+  },
+
+  buildShowResponse(input: ShowInput): ShowResponse {
+    const ext = path.extname(input.path).toLowerCase()
+
+    // For extensions supported by tool-runner, show runCmd
+    if (RUNNABLE_EXTENSIONS.has(ext)) {
+      const stashDirs = input.stashDirs ?? []
+      const assetStashDir = stashDirs.find((d) =>
+        path.resolve(input.path).startsWith(path.resolve(d) + path.sep),
+      ) ?? stashDirs[0]
+
+      if (assetStashDir) {
+        try {
+          const toolInfo = buildToolInfo(assetStashDir, input.path)
+          return {
+            type: "script",
+            name: input.name,
+            path: input.path,
+            runCmd: toolInfo.runCmd,
+            kind: toolInfo.kind,
+          }
+        } catch {
+          // Fall through to content display
+        }
+      }
+    }
+
+    // For other extensions or when buildToolInfo fails, show file content
+    return {
+      type: "script",
+      name: input.name,
+      path: input.path,
+      content: input.content,
+    }
+  },
+
+  enrichSearchHit(hit: LocalSearchHit, stashDir: string): void {
+    const ext = path.extname(hit.path).toLowerCase()
+    if (!RUNNABLE_EXTENSIONS.has(ext)) return
+
+    try {
+      const toolInfo = buildToolInfo(stashDir, hit.path)
+      hit.runCmd = toolInfo.runCmd
+      hit.kind = toolInfo.kind
+    } catch (error: unknown) {
+      if (!hasErrnoCode(error, "ENOENT")) throw error
+    }
+  },
+
+  defaultUsageGuide: [
+    "Use the hit's runCmd for execution when available, or run the script directly with the appropriate interpreter.",
+    "Use `akm show <openRef>` to inspect the script before running it.",
+  ],
+
+  extractTypeMetadata(entry: StashEntry, file: string, ext: string): void {
+    if (ext !== ".md") {
+      const commentDesc = extractDescriptionFromComments(file)
+      if (commentDesc && !entry.description) {
+        entry.description = commentDesc
+        entry.source = "comments"
+        entry.confidence = 0.7
+      }
+    }
+  },
+}

package/src/handlers/skill-handler.ts

@@ -0,0 +1,37 @@
+import path from "node:path"
+import { toPosix } from "../common"
+import type { AssetTypeHandler, ShowInput } from "../asset-type-handler"
+import type { ShowResponse } from "../stash-types"
+
+export const skillHandler: AssetTypeHandler = {
+  typeName: "skill",
+  stashDir: "skills",
+
+  isRelevantFile(fileName: string): boolean {
+    return fileName === "SKILL.md"
+  },
+
+  toCanonicalName(typeRoot: string, filePath: string): string | undefined {
+    const relDir = toPosix(path.dirname(path.relative(typeRoot, filePath)))
+    if (!relDir || relDir === ".") return undefined
+    return relDir
+  },
+
+  toAssetPath(typeRoot: string, name: string): string {
+    return path.join(typeRoot, name, "SKILL.md")
+  },
+
+  buildShowResponse(input: ShowInput): ShowResponse {
+    return {
+      type: "skill",
+      name: input.name,
+      path: input.path,
+      content: input.content,
+    }
+  },
+
+  defaultUsageGuide: [
+    "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.",
+  ],
+}

package/src/handlers/tool-handler.ts

@@ -0,0 +1,71 @@
+import path from "node:path"
+import { SCRIPT_EXTENSIONS } from "../asset-spec"
+import { hasErrnoCode, toPosix } from "../common"
+import { buildToolInfo } from "../tool-runner"
+import { extractDescriptionFromComments } from "../metadata"
+import type { AssetTypeHandler, ShowInput } from "../asset-type-handler"
+import type { ShowResponse, LocalSearchHit } from "../stash-types"
+import type { StashEntry } from "../metadata"
+
+export const toolHandler: AssetTypeHandler = {
+  typeName: "tool",
+  stashDir: "tools",
+
+  isRelevantFile(fileName: string): boolean {
+    return SCRIPT_EXTENSIONS.has(path.extname(fileName).toLowerCase())
+  },
+
+  toCanonicalName(typeRoot: string, filePath: string): string | undefined {
+    return toPosix(path.relative(typeRoot, filePath))
+  },
+
+  toAssetPath(typeRoot: string, name: string): string {
+    return path.join(typeRoot, name)
+  },
+
+  buildShowResponse(input: ShowInput): ShowResponse {
+    const stashDirs = input.stashDirs ?? []
+    const assetStashDir = stashDirs.find((d) =>
+      path.resolve(input.path).startsWith(path.resolve(d) + path.sep),
+    ) ?? stashDirs[0]
+
+    if (!assetStashDir) {
+      return { type: "tool", name: input.name, path: input.path, content: input.content }
+    }
+
+    const toolInfo = buildToolInfo(assetStashDir, input.path)
+    return {
+      type: "tool",
+      name: input.name,
+      path: input.path,
+      runCmd: toolInfo.runCmd,
+      kind: toolInfo.kind,
+    }
+  },
+
+  enrichSearchHit(hit: LocalSearchHit, stashDir: string): void {
+    try {
+      const toolInfo = buildToolInfo(stashDir, hit.path)
+      hit.runCmd = toolInfo.runCmd
+      hit.kind = toolInfo.kind
+    } catch (error: unknown) {
+      if (!hasErrnoCode(error, "ENOENT")) throw error
+    }
+  },
+
+  defaultUsageGuide: [
+    "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.",
+  ],
+
+  extractTypeMetadata(entry: StashEntry, file: string, ext: string): void {
+    if (SCRIPT_EXTENSIONS.has(ext) && ext !== ".md") {
+      const commentDesc = extractDescriptionFromComments(file)
+      if (commentDesc && !entry.description) {
+        entry.description = commentDesc
+        entry.source = "comments"
+        entry.confidence = 0.7
+      }
+    }
+  },
+}