AI Tools — Tool Registry

• Area: Intelligence
• Path: services/ai/tools
• Kind: Tool registry for AI agents (discovery, schemas, permissions, versioning)
• Status: v0.0.3 — 2026-05-28 k-go drain shipped invoke telemetry (#024), MCP invoke dispatcher (#022), live HTTPSSE mcp-registry source (#012), SSE change stream + Go SDK Subscribe (#007 tools-side), auto-skill mining worker (#020), built-in integration packs + webhook dispatcher (#015), and the build-tagged kdb-doc adapter (#006). Remaining pending: #016#019 (cross-component in `servicesai/ai`).

Role in the stack

tools is the registry that materializes what was previously implicit: every AI consumer (kode, agents, kortex, playground, workflow) needs to know what tools exist, what their schemas are, what permissions they require, and which version is current. Today every consumer hardcodes its own tool list — copy-pasted JSON schemas, no versioning, no deprecation, no shared discovery. When a tool changes its schema everyone breaks silently. This sector consolidates the capability into one source of truth.

It is the Koder analog of OpenAI tools catalog and Anthropic tool catalog (which exist as implicit SDK constructs but not as queryable services). Distinct from mcp-registry — mcp-registry is the source of truth for MCP servers; tools is the superset registry queried by all consumers, which mirrors mcp-registry one-way.

Boundary vs neighbors

• services/ai/mcp-registry is the upstream catalog for MCP-server tools; tools mirrors them in. Pair-decision tracked in services/ai/mcp-registry ticket #140.
• services/ai/agents, services/ai/kode, services/ai/playground, services/ai/workflow are the primary consumers — bootstrap their tool surface from this registry.
• products/dev/kortex consumes via IDE-side tool palette.
• services/ai/sandbox is the runtime backend for sandbox-runnable tools (tools registers, sandbox executes).

Features (v1 target)

• Tool + version + permission entities backed by kdb-doc
• Semver versioning with breaking-change rules enforced
• Discovery API with multi-axis search + pagination + etag caching
• Bulk lookup endpoint (agent boot optimization, single round-trip)
• Permission catalog (12 baseline permissions) + per-tenant grants
• One-way mcp-registry mirror (scheduled poll + SSE event-driven)
• Deprecation flow (90-day sunset window, replacement tool ref)
• SDK helpers (Go + Dart) with etag cache + change subscription
• Boot-pattern reference doc

Primary couplings

RFC and bootstrap

• RFC: tools-RFC-001-foundations.kmd — accepted 2026-05-09
• Bootstrap ticket: services/ai/backlog/done/135-tools-bootstrap.md
• Schema: schema-v1.md — accepted 2026-05-09 via #001
• Backend: koder-tools + OpenAPI /openapi.json — shipped 2026-05-10 via #002 (PUTGETdiscoverlookupversions/schema endpoints, ETag, semver enforcement, cursor pagination, JWKSValidator + dev-token middleware, in-memory store, 26 tests)
• Implementation tickets:
  • done/: 001 (entity schema), 002 (discovery API + multi-axis search + version pinning + bulk lookup + ETag + OpenAPI), 003 (permission catalog + per-tenant grants + IsAllowed enforcement + 4 admin endpoints + slog audit), 004 (mcp-registry mirror machinery + capability→permission map + status endpoint + PUT-guard for mcp-sourced tools), 005 (Go SDK engines/sdk/go/tools + mock server + boot-pattern doc), 008 (split — store.DeprecateVersion helper + mirror wire-up shipped 2026-05-11; live HTTP/SSE client deferred to #012)
  • pending/: 006 (kdb-doc store adapter — same upstream blocker as cache#007), 007 (Dart binding + SSE Subscribe + consumer migration sweep — closes the deferred portion of #005), 012 (live mcp-registry HTTPSSE source — blocked by `servicesai/mcp-registry` having no backend yet)

Recent changes

• 2026-05-28 (k-go drain — #006#007#012#015#020#022/#024 + follow-ups) — six tickets implemented in-sector plus the #007 tools-side, all default-build-safe + tested:
  • #024 per-invoke telemetry — internal/observe: Observer seam (InvokeStartedInvokeFinished) + NopMultiTraceObserver (dependency-free TracerMetrics seams → span tool.invoke + counter koder_tools_invoke_total + histogram koder_tools_invoke_duration_ms), wired in the invoke handler. Workflow tool-executor wiring is the cross-component tail.
  • #022 MCP dispatcher — internal/mcpinvoker: Invoker over a Caller, parses mcp://server/tool, maps R7 (4xx terminal / 5xx+timeout retryable). Wired behind [invoke] mcp_enabled (Registry.BySource["mcp-registry"]). Unit + API end-to-end test.
  • #012 live HTTP/SSE mcp-registry source — internal/mcpmirror/http_source.go: HTTPSource implements MCPSource (Snapshot) + SSE Subscribe (reconnectbackoffLast-Event-ID) + mcpinvoker.Caller (CallTool). Behind [mcp_mirror] source=http; FakeSource stays dev default. SSE nudges mirror.SyncOnce; poll loop is the safety net.
  • #007 SSE events + Go SDK Subscribe — internal/events hub + GET /v1/tools/events (1024-event ring, Last-Event-ID replay, heartbeat); emits tool.released (PUT) + tool.deprecated (mirror removal via Mirror.OnDeprecate). Go SDK tools.Client.Subscribe (auto-reconnect) + mock events endpoint. Migration guide docs/migration-agents.kmd + 5 consumer tickets (agents#026, kode#109, playground#006, workflow#021, kortex#001). Dart binding → koder_kit#070.
  • #020 auto-skill mining worker — internal/miningworker: scheduled idempotent single-tenant Worker over RunSource+SuggestionSink seams, consumes mining.Mine, opt-out honoured, default OFF. HTTPRunSource (2026-06-02) is the production RunSource over the gateway read API (gateway#055: GET /v1/runs/tenants + GET /v1/runs?tenant=&since=, service-account bearer; runDTO decodes the projection → mining.Run), replacing FakeRunSource on the prod path. End-to-end-over-HTTP test: a gateway stub serving 3 similar rated runs mines one suggestion through the real client. koder-skill worker (2026-06-02) is the scheduled daemon: it wires the HTTPRunSource (gateway URL + service token via flags$KODER_SKILL_GATEWAY_{URL,TOKEN}) + a FileSink (writes mined SKILL.md drafts to `--outtenantslug.md, idempotent), --once for cron else loops on --interval`. The vertical is now end-to-end runnable in prod; the richer dashboard-card SuggestionSink (servicesaiaiweb) + EMBED-013 similarity stay the only tails.
  • #015 built-in integration packs — internal/packs: GitHubFlowSlackJiraWebhook tool defs registered (idempotent, catalog-slug perms) + webhook.post live dispatcher (HMAC verify/sign + outbound POST with per-workspace https allowlist). Behind [integrations]. OAuth-backed live dispatchers → tools#025.
  • #006 kdb-doc store adapter — store/kdb_store.go behind //go:build kdb (two KV tables, JSON rows, prefix-scan versions, post-filter Discover), buildStore cmd selector + KDBStoreConfig, integ test kdb && integ. Default build/CI unaffected; runtime SDK init-panic blocker (cache#007) remains external.
  • Remaining pending: #016#019 (cross-component in `servicesaiai); #019 blocked on promoting the skills loader out of internal → tools#026`.
• 2026-05-25 (#014 — auto-skill mining engine + koder-skill mine) — deterministic core of TOOLS-014 (Manus-style "you've done this 3 times, make it a skill"). backend/internal/mining: Mine(runs, opts) clusters a single tenant's well-rated runs (rating ≥4, 30d window) by tool-set Jaccard similarity (≥0.6), keeps clusters of ≥3, and DraftSkill emits a validated SKILL.md draft (reusing the #013#017#018 parser+validator — no duplication), RenderMarkdown serialises it. koder-skill mine <runs.json> subcommand prints suggested drafts. 8 tests (5 acceptance scenarios + window + cross-tenant fail-safe + draft-validates-and-is-deterministic). Cross-component tails (24h worker, agent_runs source from the gateway, EMBED-013 vector similarity, dashboard "suggested skills" cards, settings toggle) split to #020. Spoke of AICORE-119 (Manus-parity umbrella).
• 2026-05-18 (#013 umbrella close — SKILL.md tooling slice) — closes the spec-+-contained-tooling slice of #013. Ships backend/internal/skill (parser, validator, intent taxonomy, KAI-SKILL-* error model), backend/cmd/koder-skill (CLI: validate / dry-run / lint, --json for CI, T1–T6 static checks, 0.1–0.2 ms typical), backend/internal/skills (runtime loader with workspace > user-local > bundled precedence, polling hot-reload at 1s default, trigger matcher prioritising regex > literal > intent, workspace tenant filter). 5 spec fixtures + 4 loader T-tests. Closes #018 and #017; remaining #016 (slash command across CLIWebDesktop surfaces of koder-ai) and #019 (agent-side auto-load consumer) stay pending under separate services/ai/ai lock scopes.
• 2026-05-11 (#008 split + DeprecateVersion ship) — #008 split into "DeprecateVersion helper" (this commit) + "live HTTPSSE client" (#012, blocked by upstream sector). store.Store gains DeprecateVersion(ctx, name, version, deprecatedAt, sunsetAt) — the dedicated escape hatch for released-version immutability. MemoryStore impl stamps Version.DeprecatedAt + Version.SunsetAt, returns ErrNotFound for absent pairs, idempotent (last-write-wins). Mirror.deprecateLatestVersion now calls DeprecateVersion and logs mcpmirror.deprecate.applied.failed instead of the previous .pending stub. +4 tests (ST16-ST18 store, MM9 mirror end-to-end). The mirror is now operationally complete (modulo the live source in #012).

Self-hosted-first analysis (5 gates)