@agentskit/doc-bridge 0.1.0-alpha.1 → 0.1.0-alpha.2

package/src/index.ts

@@ -0,0 +1,120 @@
+export { defineConfig } from './config/define-config.js'
+export { applyConfigDefaults } from './config/defaults.js'
+export {
+  loadConfig,
+  resolveProjectRoot,
+  ConfigNotFoundError,
+  type LoadConfigOptions,
+  type LoadConfigResult,
+} from './config/load-config.js'
+export {
+  DocBridgeConfigV1Schema,
+  type DocBridgeConfigV1,
+  type AgentCorpusConfig,
+} from './config/schema.js'
+
+export {
+  AgentHandoffV1Schema,
+  AgentHandoffLegacySchema,
+  AgentSearchV1Schema,
+  HandoffTargetTypeSchema,
+  HANDOFF_SCHEMA_VERSION,
+  normalizeAgentHandoff,
+  type AgentHandoffV1,
+  type AgentSearchV1,
+  type HandoffTarget,
+  type HandoffTargetType,
+} from './schemas/agent-handoff.js'
+
+export {
+  DocBridgeIndexV1Schema,
+  KnowledgeEntrySchema,
+  INDEX_SCHEMA_VERSION,
+  type DocBridgeIndexV1,
+  type KnowledgeEntry,
+} from './schemas/doc-bridge-index.js'
+
+export {
+  MemoryCandidateV1Schema,
+  MEMORY_CANDIDATE_SCHEMA_VERSION,
+  type MemoryCandidateV1,
+} from './schemas/memory-candidate.js'
+
+export {
+  AgentHandoffV1JsonSchema,
+  DocBridgeIndexV1JsonSchema,
+  DocBridgeJsonSchemas,
+  MemoryCandidateV1JsonSchema,
+} from './schemas/json-schemas.js'
+
+export {
+  parseAgentHandoff,
+  parseAgentSearch,
+  parseDocBridgeConfig,
+  parseDocBridgeIndex,
+  parseMemoryCandidate,
+  safeParseAgentHandoff,
+  type ParseIssue,
+  type ParseResult,
+} from './validate.js'
+
+export { buildDocBridgeIndex, type BuildIndexOptions, type BuildIndexResult } from './index-builder/build-index.js'
+export {
+  scanHumanDocRecords,
+  scanHumanDocs,
+  type HumanDocMap,
+  type HumanDocRecord,
+} from './index-builder/plugins/human-markdown.js'
+export {
+  resolveGateIds,
+  runGate,
+  runGates,
+  type GateId,
+  type GateResult,
+  type GateRunResult,
+} from './gates/run-gates.js'
+export { MCP_TOOLS, handleMcpRequest, startMcpStdioServer } from './mcp/server.js'
+export { sha256NormalizedV1 } from './index-builder/content-hash.js'
+export { IndexNotFoundError, indexFilePath, loadDocBridgeIndex, resolveRoot } from './query/load-index.js'
+export { runQuery, type QueryKind, type QueryRequest, type QueryResult } from './query/query.js'
+export { searchIndex, type SearchMatch } from './query/search.js'
+export {
+  ingestAgentMemory,
+  ingestCursorRules,
+  ingestMemoryCandidates,
+} from './memory/ingest.js'
+
+export {
+  classifyMemoryCandidates,
+  draftMemoryPromotion,
+  scanMemorySafety,
+  type MemoryClassification,
+  type MemoryPromotionDraft,
+  type MemoryRoute,
+  type SafetyFinding,
+} from './memory/pipeline.js'
+
+export {
+  chunksFromMarkdown,
+  loadFederatedChunks,
+  parseLlmsTxtLinks,
+  retrieveHybridChunks,
+  type FederatedRetrieverOptions,
+  type FetchText,
+} from './federation/llms.js'
+
+export {
+  createDocBridgeRetriever,
+  retrieveDocBridgeChunks,
+  type DocBridgeRetrievedChunk,
+  type DocBridgeRetriever,
+  type DocBridgeRetrieverOptions,
+} from './retriever/doc-bridge-retriever.js'
+
+export { PACKAGE_VERSION } from './version.js'
+
+export { collectPackages, buildLookup } from './index-builder/build-handoffs.js'
+export { projectRootFromConfigPath } from './config/load-config.js'
+export { createDocBridgeRag } from './intelligence/rag.js'
+export { runChatOnce, startInkChat } from './intelligence/chat.js'
+export { PeerMissingError, layer1InstallHint } from './intelligence/peers.js'

package/src/intelligence/adapter.ts

@@ -0,0 +1,90 @@
+import { join } from 'node:path'
+
+import type { DocBridgeConfigV1 } from '../config/schema.js'
+import { importPeer } from './peers.js'
+
+const readEnv = (name: string | undefined): string | undefined => {
+  if (!name) return undefined
+  const value = process.env[name]
+  return value && value.length > 0 ? value : undefined
+}
+
+export type ResolvedIntelligence = {
+  readonly adapter: unknown
+  readonly embed: unknown
+  readonly provider: string
+  readonly model?: string
+}
+
+export const resolveIntelligenceRuntime = async (
+  config: DocBridgeConfigV1,
+): Promise<ResolvedIntelligence> => {
+  if (!config.intelligence?.enabled) {
+    throw new Error('Intelligence is disabled. Set intelligence.enabled: true in doc-bridge config.')
+  }
+  const adapterCfg = config.intelligence.adapter
+  if (!adapterCfg) {
+    throw new Error('intelligence.adapter is required for chat/RAG (provider + optional model).')
+  }
+
+  const adapters = await importPeer<typeof import('@agentskit/adapters')>('@agentskit/adapters')
+  const provider = adapterCfg.provider
+  const model = adapterCfg.model
+  const apiKey = readEnv(adapterCfg.apiKeyEnv) ?? readEnv('OPENAI_API_KEY') ?? readEnv('ANTHROPIC_API_KEY')
+  const baseUrl = adapterCfg.baseUrl
+
+  let adapter: unknown
+  let embed: unknown
+
+  switch (provider) {
+    case 'ollama': {
+      adapter = adapters.ollama({ model: model ?? 'llama3.2', ...(baseUrl ? { baseUrl } : {}) })
+      embed = adapters.ollamaEmbedder({
+        model: typeof adapterCfg.options?.embedModel === 'string'
+          ? adapterCfg.options.embedModel
+          : 'nomic-embed-text',
+        ...(baseUrl ? { baseUrl } : {}),
+      })
+      break
+    }
+    case 'openai': {
+      if (!apiKey) throw new Error(`Missing API key env ${adapterCfg.apiKeyEnv ?? 'OPENAI_API_KEY'}`)
+      adapter = adapters.openai({ apiKey, ...(model ? { model } : {}), ...(baseUrl ? { baseUrl } : {}) })
+      embed = adapters.openaiEmbedder({ apiKey, model: 'text-embedding-3-small' })
+      break
+    }
+    case 'anthropic': {
+      if (!apiKey) throw new Error(`Missing API key env ${adapterCfg.apiKeyEnv ?? 'ANTHROPIC_API_KEY'}`)
+      adapter = adapters.anthropic({ apiKey, ...(model ? { model } : {}) })
+      // Anthropic has no default embedder in adapters — fall back to openai-compatible if key present
+      const openaiKey = readEnv('OPENAI_API_KEY')
+      if (openaiKey) embed = adapters.openaiEmbedder({ apiKey: openaiKey })
+      else {
+        throw new Error(
+          'Anthropic chat requires an embedder for RAG. Set OPENAI_API_KEY for embeddings or use provider: ollama.',
+        )
+      }
+      break
+    }
+    case 'openrouter': {
+      if (!apiKey) throw new Error(`Missing API key env ${adapterCfg.apiKeyEnv ?? 'OPENROUTER_API_KEY'}`)
+      adapter = adapters.openrouter({ apiKey, ...(model ? { model } : {}) })
+      embed = adapters.openaiEmbedder({
+        apiKey,
+        model: 'text-embedding-3-small',
+        // openrouter embeddings path may vary; adapters handle openai-compatible
+      })
+      break
+    }
+    case 'custom':
+      throw new Error(
+        'provider: custom requires a programmatic integration. Use ollama, openai, anthropic, or openrouter in v0.1.',
+      )
+    default:
+      throw new Error(`Unsupported intelligence.adapter.provider: ${String(provider)}`)
+  }
+
+  return { adapter, embed, provider, ...(model ? { model } : {}) }
+}
+
+export const defaultVectorStorePath = (root: string): string => join(root, '.doc-bridge', 'vectors')

package/src/intelligence/chat.ts

@@ -0,0 +1,148 @@
+import type { DocBridgeConfigV1 } from '../config/schema.js'
+import type { DocBridgeIndexV1 } from '../schemas/doc-bridge-index.js'
+import { runQuery } from '../query/query.js'
+import { resolveIntelligenceRuntime } from './adapter.js'
+import {
+  PeerMissingError,
+  importPeer,
+  isPeerResolutionFailure,
+  layer1InstallHint,
+} from './peers.js'
+import { createDocBridgeRag } from './rag.js'
+
+const wrapIntelligenceError = (error: unknown): Error => {
+  if (error instanceof PeerMissingError) return error
+  if (isPeerResolutionFailure(error)) {
+    return new PeerMissingError('@agentskit/*', layer1InstallHint())
+  }
+  const message = error instanceof Error ? error.message : String(error)
+  if (/fetch failed|econnrefused|enotfound|network|socket/i.test(message)) {
+    return new Error(
+      `Intelligence provider request failed (${message}).\n` +
+        `Check the model server (e.g. \`ollama serve\`) and Layer 1 peers:\n  ${layer1InstallHint()}`,
+    )
+  }
+  return error instanceof Error ? error : new Error(message)
+}
+
+const handoffFirstHint = (
+  index: DocBridgeIndexV1,
+  config: DocBridgeConfigV1,
+  question: string,
+): string | undefined => {
+  if (config.intelligence?.chat?.handoffFirst === false) return undefined
+  const tokens = question
+    .toLowerCase()
+    .split(/[^a-z0-9@/_-]+/)
+    .filter((t) => t.length >= 2)
+  const packages = index.lookup?.packages ?? []
+  const hit = packages.find((id) => tokens.includes(id.toLowerCase()))
+  if (!hit) return undefined
+  try {
+    const handoff = runQuery(index, config, { kind: 'ownership', id: hit, agent: true })
+    return [
+      '## Deterministic AgentHandoff (prefer for edits)',
+      '```json',
+      JSON.stringify(handoff, null, 2),
+      '```',
+      'Use startHere / editRoots / checks before broad exploration.',
+    ].join('\n')
+  } catch {
+    return undefined
+  }
+}
+
+const systemPrompt = (
+  index: DocBridgeIndexV1,
+  config: DocBridgeConfigV1,
+  provider: string,
+  model: string | undefined,
+  question?: string,
+): string => {
+  const prefix = question ? handoffFirstHint(index, config, question) : undefined
+  return [
+    'You are a documentation assistant for this repository (doc-bridge).',
+    'Prefer deterministic AgentHandoff fields for code edits.',
+    'Cite file paths from retrieved context.',
+    `Provider: ${provider}${model ? ` / ${model}` : ''}.`,
+    'If unsure, suggest: ak-docs query ownership <id> --agent or MCP handoff.resolve.',
+    prefix ?? '',
+  ]
+    .filter(Boolean)
+    .join('\n\n')
+}
+
+export const runChatOnce = async (
+  root: string,
+  config: DocBridgeConfigV1,
+  index: DocBridgeIndexV1,
+  question: string,
+): Promise<{ content: string; handoffPrefixed: boolean }> => {
+  try {
+    const { adapter, provider, model } = await resolveIntelligenceRuntime(config)
+    const core = await importPeer<typeof import('@agentskit/core')>('@agentskit/core')
+    const rag = await createDocBridgeRag(root, config, index)
+    await rag.ingest()
+
+    const controller = core.createChatController({
+      adapter,
+      retriever: rag.retriever,
+      system: systemPrompt(index, config, provider, model, question),
+    })
+
+    const result = await controller.send(question)
+    const content =
+      typeof result?.content === 'string' ? result.content : JSON.stringify(result, null, 2)
+
+    return {
+      content,
+      handoffPrefixed: Boolean(handoffFirstHint(index, config, question)),
+    }
+  } catch (error) {
+    throw wrapIntelligenceError(error)
+  }
+}
+
+export const startInkChat = async (
+  root: string,
+  config: DocBridgeConfigV1,
+  index: DocBridgeIndexV1,
+): Promise<void> => {
+  try {
+    const { adapter, provider, model } = await resolveIntelligenceRuntime(config)
+    const rag = await createDocBridgeRag(root, config, index)
+    await rag.ingest()
+
+    const React = await importPeer<typeof import('react')>('react')
+    const ink = await importPeer<typeof import('ink')>('ink')
+    const agentskitInk = await importPeer<typeof import('@agentskit/ink')>('@agentskit/ink')
+
+    const App = () => {
+      const chat = agentskitInk.useChat({
+        adapter,
+        retriever: rag.retriever,
+        system: systemPrompt(index, config, provider, model),
+      })
+
+      return React.createElement(
+        agentskitInk.ChatContainer as never,
+        null,
+        ...chat.messages.map((msg) =>
+          React.createElement(agentskitInk.Message as never, {
+            key: msg.id,
+            message: msg,
+          } as never),
+        ),
+        React.createElement(agentskitInk.InputBar as never, {
+          chat,
+          placeholder: 'Ask about project docs (handoff-first RAG)…',
+        } as never),
+      )
+    }
+
+    const instance = ink.render(React.createElement(App))
+    await instance.waitUntilExit()
+  } catch (error) {
+    throw wrapIntelligenceError(error)
+  }
+}

package/src/intelligence/peers.ts

@@ -0,0 +1,59 @@
+export class PeerMissingError extends Error {
+  constructor(
+    readonly peer: string,
+    readonly installHint: string,
+  ) {
+    super(
+      `Optional peer "${peer}" is not installed.\nInstall Layer 1 intelligence peers:\n  ${installHint}`,
+    )
+    this.name = 'PeerMissingError'
+  }
+}
+
+const LAYER1_INSTALL =
+  'npm i -D @agentskit/rag @agentskit/ink @agentskit/adapters @agentskit/memory react'
+
+/** True when a dynamic import failed because the package could not be resolved/loaded. */
+export const isPeerResolutionFailure = (error: unknown): boolean => {
+  const parts: string[] = []
+  let cur: unknown = error
+  for (let i = 0; i < 6 && cur; i += 1) {
+    if (cur instanceof Error) {
+      parts.push(cur.message, cur.name)
+      const code = (cur as NodeJS.ErrnoException).code
+      if (code) parts.push(String(code))
+      cur = cur.cause
+      continue
+    }
+    parts.push(String(cur))
+    break
+  }
+  const text = parts.join(' ').toLowerCase()
+  return (
+    text.includes('cannot find package') ||
+    text.includes('cannot find module') ||
+    text.includes('module not found') ||
+    text.includes('err_module_not_found') ||
+    text.includes('err_package_not_found') ||
+    text.includes('err_package_path_not_exported') ||
+    text.includes('failed to resolve module') ||
+    text.includes('failed to resolve') ||
+    // Node / network resolution edge cases for bare package imports
+    text.includes('fetch failed') ||
+    text.includes('enotfound') ||
+    text.includes('getaddrinfo')
+  )
+}
+
+export const importPeer = async <T>(name: string): Promise<T> => {
+  try {
+    return (await import(name)) as T
+  } catch (error) {
+    if (isPeerResolutionFailure(error)) {
+      throw new PeerMissingError(name, LAYER1_INSTALL)
+    }
+    throw error
+  }
+}
+
+export const layer1InstallHint = (): string => LAYER1_INSTALL

package/src/intelligence/rag.ts

@@ -0,0 +1,98 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { DocBridgeConfigV1 } from '../config/schema.js'
+import type { DocBridgeIndexV1 } from '../schemas/doc-bridge-index.js'
+import { defaultVectorStorePath, resolveIntelligenceRuntime } from './adapter.js'
+import { importPeer } from './peers.js'
+
+export type RagSearchHit = {
+  readonly id?: string
+  readonly content: string
+  readonly score?: number
+  readonly source?: string
+  readonly metadata?: Record<string, unknown>
+}
+
+export type DocBridgeRag = {
+  readonly ingest: () => Promise<{ documentCount: number; storePath: string }>
+  readonly search: (query: string, topK?: number) => Promise<RagSearchHit[]>
+  readonly retriever: unknown
+  readonly storePath: string
+}
+
+const loadDocuments = (
+  root: string,
+  index: DocBridgeIndexV1,
+  sources: readonly string[],
+): Array<{ id: string; content: string; source: string; metadata: Record<string, unknown> }> => {
+  const includeAgent = sources.includes('agent') || sources.length === 0
+  const docs: Array<{ id: string; content: string; source: string; metadata: Record<string, unknown> }> = []
+
+  if (includeAgent) {
+    for (const entry of index.knowledge) {
+      const abs = join(root, entry.path)
+      let content = ''
+      try {
+        content = readFileSync(abs, 'utf8')
+      } catch {
+        content = [entry.title, entry.description].filter(Boolean).join('\n\n')
+      }
+      docs.push({
+        id: entry.id,
+        content,
+        source: entry.path,
+        metadata: { type: entry.type, title: entry.title, path: entry.path },
+      })
+    }
+  }
+
+  // Human corpus is linked via humanDoc URLs; optional future: ingest human paths from adapters
+  return docs
+}
+
+export const createDocBridgeRag = async (
+  root: string,
+  config: DocBridgeConfigV1,
+  index: DocBridgeIndexV1,
+): Promise<DocBridgeRag> => {
+  const { embed } = await resolveIntelligenceRuntime(config)
+  const ragMod = await importPeer<typeof import('@agentskit/rag')>('@agentskit/rag')
+  const memoryMod = await importPeer<typeof import('@agentskit/memory')>('@agentskit/memory')
+
+  const storePath =
+    typeof config.intelligence?.retriever?.options?.storePath === 'string'
+      ? join(root, config.intelligence.retriever.options.storePath)
+      : defaultVectorStorePath(root)
+
+  const store = memoryMod.fileVectorMemory({ path: storePath })
+  const rag = ragMod.createRAG({
+    embed,
+    store,
+    topK: 6,
+    chunkSize: 900,
+    chunkOverlap: 120,
+  })
+
+  const sources = config.intelligence?.chat?.sources ?? ['agent', 'human']
+
+  return {
+    storePath,
+    retriever: rag,
+    ingest: async () => {
+      const documents = loadDocuments(root, index, sources)
+      await rag.ingest(documents)
+      return { documentCount: documents.length, storePath }
+    },
+    search: async (query, topK = 6) => {
+      const hits = await rag.search(query, { topK })
+      return hits.map((hit) => ({
+        ...(hit.id ? { id: hit.id } : {}),
+        content: hit.content,
+        ...(hit.score !== undefined ? { score: hit.score } : {}),
+        ...(hit.source ? { source: hit.source } : {}),
+        ...(hit.metadata ? { metadata: hit.metadata } : {}),
+      }))
+    },
+  }
+}

package/src/lib/glob-expand.ts

@@ -0,0 +1,33 @@
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { toPosix } from './paths.js'
+
+/** Expand simple workspace globs: `packages/*`, `apps/*`, literal paths. */
+export const expandWorkspaceGlobs = (root: string, patterns: readonly string[]): string[] => {
+  const dirs = new Set<string>()
+
+  for (const pattern of patterns) {
+    const normalized = toPosix(pattern).replace(/\/$/, '')
+    if (!normalized.includes('*')) {
+      const abs = join(root, normalized)
+      if (existsSync(abs)) dirs.add(toPosix(abs))
+      continue
+    }
+
+    const star = normalized.indexOf('*')
+    const base = join(root, normalized.slice(0, star).replace(/\/$/, ''))
+    if (!existsSync(base)) continue
+
+    for (const name of readdirSync(base)) {
+      const abs = join(base, name)
+      try {
+        if (statSync(abs).isDirectory()) dirs.add(toPosix(abs))
+      } catch {
+        // skip
+      }
+    }
+  }
+
+  return [...dirs].sort()
+}

package/src/lib/markdown.ts

@@ -0,0 +1,90 @@
+export type FrontmatterValue = string | boolean | readonly string[]
+export type FrontmatterData = Record<string, FrontmatterValue>
+
+export const parseFrontmatter = (
+  markdown: string,
+): { readonly data: FrontmatterData; readonly body: string } => {
+  const normalized = markdown.replace(/^\uFEFF/, '')
+  if (!normalized.startsWith('---\n') && !normalized.startsWith('---\r\n')) {
+    return { data: {}, body: markdown }
+  }
+  const endMatch = /\r?\n---\r?\n/.exec(normalized.slice(3))
+  if (!endMatch || endMatch.index === undefined) {
+    return { data: {}, body: markdown }
+  }
+  const block = normalized.slice(4, 3 + endMatch.index)
+  const body = normalized.slice(3 + endMatch.index + endMatch[0].length)
+  const data: Record<string, FrontmatterValue> = {}
+  for (const rawLine of block.split(/\r?\n/)) {
+    const line = rawLine.trim()
+    if (!line || line.startsWith('#')) continue
+    const m = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line)
+    if (!m?.[1]) continue
+    const key = m[1]
+    const raw = (m[2] ?? '').trim()
+    if (raw === 'true') data[key] = true
+    else if (raw === 'false') data[key] = false
+    else if (raw.startsWith('[') && raw.endsWith(']')) {
+      data[key] = raw
+        .slice(1, -1)
+        .split(',')
+        .map((part) => part.trim().replace(/^['"]|['"]$/g, ''))
+        .filter(Boolean)
+    } else {
+      data[key] = raw.replace(/^['"]|['"]$/g, '')
+    }
+  }
+  return { data, body }
+}
+
+export const frontmatterString = (
+  data: FrontmatterData,
+  key: string,
+): string | undefined => {
+  const value = data[key]
+  return typeof value === 'string' && value.length > 0 ? value : undefined
+}
+
+export const frontmatterStringList = (
+  data: FrontmatterData,
+  key: string,
+): string[] | undefined => {
+  const value = data[key]
+  if (Array.isArray(value)) return value.filter((item): item is string => typeof item === 'string')
+  if (typeof value === 'string' && value.length > 0) return [value]
+  return undefined
+}
+
+export const firstHeading = (markdown: string): string | undefined => {
+  const { body } = parseFrontmatter(markdown)
+  for (const line of body.split('\n')) {
+    const m = /^#\s+(.+)$/.exec(line.trim())
+    if (m?.[1]) return m[1].trim()
+  }
+  return undefined
+}
+
+export const firstParagraph = (markdown: string): string | undefined => {
+  const { body } = parseFrontmatter(markdown)
+  const lines = body.split('\n')
+  const buf: string[] = []
+  for (const line of lines) {
+    const t = line.trim()
+    if (!t) {
+      if (buf.length) break
+      continue
+    }
+    if (t.startsWith('#')) continue
+    if (t.startsWith('---')) continue
+    buf.push(t)
+    if (buf.join(' ').length > 40) break
+  }
+  const text = buf.join(' ').trim()
+  return text || undefined
+}
+
+export const slugFromPath = (relPath: string): string => {
+  const base = relPath.replace(/\.mdx?$/, '')
+  const parts = base.split('/')
+  return parts[parts.length - 1] ?? base
+}