AI Tools — Tool Registry

• *rea:*Intelligence
• *ath:*services/ai/tools
• *ind:*Tool registry for AI agents (discovery, schemas, permissions, versioning)
• *tatus:*v0.0.2 — #008 split + DeprecateVersion shipped 20260511. store.DeprecateVersion is the dedicated escape hatch for releasedversion immutability; mirror's deprecateLatestVersion now persists deprecation timestamps instead of logging "pending". Live mcpregistry HTTPSSE client (was part of original #008) split off as #012, blocked by `servicesai/mcp-registry` having no backend yet.

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). *istinct from mcp-registry*— mcpregistry is the source of truth for MCP servers; tools is the superset registry queried by all consumers, which mirrors mcpregistry one-way.

Boundary vs neighbors

• services/ai/mcp-registry is the upstream catalog for MCPserver tools; tools mirrors them in. Pairdecision 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
• Oneway mcpregistry 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 — *ccepted*20260509
• Bootstrap ticket: services/ai/backlog/done/135-tools-bootstrap.md
• Schema: schema-v1.md — accepted 20260509 via #001
• Backend: koder-tools + OpenAPI /openapi.json — shipped 20260510 via #002 (PUTGETdiscoverlookupversions/schema endpoints, ETag, semver enforcement, cursor pagination, JWKSValidator + devtoken middleware, inmemory store, 26 tests)
• Implementation tickets:
  • done/: 001 (entity schema), 002 (discovery API + multiaxis search + version pinning + bulk lookup + ETag + OpenAPI), 003 (permission catalog + pertenant grants + IsAllowed enforcement + 4 admin endpoints + slog audit), 004 (mcpregistry mirror machinery + capability→permission map + status endpoint + PUTguard for mcpsourced tools), 005 (Go SDK engines/sdk/go/tools + mock server + bootpattern doc), 008 (split — store.DeprecateVersion helper + mirror wireup shipped 202605-11; live HTTP/SSE client deferred to #012)
  • pending/: 006 (kdbdoc store adapter — same upstream blocker as cache#007), 007 (Dart binding + SSE Subscribe + consumer migration sweep — closes the deferred portion of #005), 012 (live mcpregistry HTTPSSE source — blocked by `servicesai/mcp-registry` having no backend yet)

Recent changes

• *0260518 (#013 umbrella close — SKILL.md tooling slice)*— closes the spec+containedtooling slice of #013. Ships backend/internal/skill (parser, validator, intent taxonomy, `KAISKILL* error model), backendcmdkoderskill (CLI: validate / dryrun / lint, json for CI, T1–T6 static checks, 0.1–0.2 ms typical), backendinternalskills` (runtime loader with workspace > userlocal > bundled precedence, polling hotreload at 1s default, trigger matcher prioritising regex > literal > intent, workspace tenant filter). 5 spec fixtures + 4 loader Ttests. Closes #018 and #017; remaining #016 (slash command across CLIWebDesktop surfaces of koderai) and #019 (agentside auto-load consumer) stay pending under separate services/ai/ai lock scopes.
• *0260511 (#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 releasedversion immutability. MemoryStore impl stamps Version.DeprecatedAt + Version.SunsetAt, returns ErrNotFound for absent pairs, idempotent (lastwrite-wins). Mirror.deprecateLatestVersion now calls DeprecateVersion and logs mcpmirror.deprecate.applied.failed instead of the previous .pending stub. +4 tests (ST16ST18 store, MM9 mirror endto-end). The mirror is now operationally complete (modulo the live source in #012).

Selfhostedfirst analysis (5 gates)