@company-semantics/contracts 0.20.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/guards/config.ts

@@ -319,11 +319,6 @@ export interface GuardCheckRegistry {
     structural?: BoundGuardCheck[];
     behavioral?: BoundGuardCheck[];
     invariants?: BoundGuardCheck[];
-    /**
-     * @deprecated Evolution guards are CI-owned. Use evolutionBaselines instead.
-     * Product repos should not provide evolution check implementations.
-     */
-    evolution?: BoundGuardCheck[];
     /** Meta-guards: protect the guard system itself (coverage correctness) */
     meta?: BoundGuardCheck[];
   };

package/src/index.ts

@@ -84,3 +84,19 @@ export {
 // @see ADR-2025-12-011 for design rationale
 export { COMPATIBILITY } from './compatibility.js'
 export type { Compatibility, Deprecation } from './compatibility.js'
+
+// User identity types and functions
+// @see ADR-2026-01-020 for design rationale
+export type { ISODateString, UserIdentity } from './identity/index.js'
+export { deriveFullName, resolveDisplayName } from './identity/index.js'
+
+// MCP tool discovery types
+// @see company-semantics-backend/src/interfaces/mcp/ for implementation
+export type {
+  ToolCategory,
+  ToolVisibility,
+  ToolInvocationMode,
+  MCPToolDescriptor,
+  ToolDiscoveryResponse,
+  ToolListMessagePart,
+} from './mcp/index.js'

package/src/mcp/index.ts

@@ -0,0 +1,85 @@
+/**
+ * MCP Tool Discovery Types
+ *
+ * Types for tool discovery flow (read-only, UI-first).
+ * Same descriptor used for discovery and invocation, different fields matter.
+ *
+ * INVARIANTS:
+ * - Discovery is descriptive (never executes)
+ * - Invocation is authoritative (runtime is executor)
+ * - Tool discovery output must be runtime-sourced
+ * - Tool discovery must not be streamed char-by-char
+ *
+ * @see company-semantics-backend/src/interfaces/mcp/ for implementation
+ */
+
+/**
+ * Tool categories for grouping in UI.
+ * Maps to user mental model, not implementation.
+ */
+export type ToolCategory =
+  | 'system' // System status, health checks
+  | 'data' // Data access, ingestion, queries
+  | 'connections' // OAuth, integrations
+  | 'automation' // Scheduled tasks, triggers
+  | 'developer' // Debug, internal tools
+
+/**
+ * Tool visibility levels.
+ * Controls who can see the tool in discovery.
+ */
+export type ToolVisibility = 'user' | 'admin'
+
+/**
+ * How the tool can be invoked.
+ * - manual: User must explicitly request
+ * - assistant: AI can invoke proactively
+ * - hybrid: Both manual and assistant invocation
+ */
+export type ToolInvocationMode = 'manual' | 'assistant' | 'hybrid'
+
+/**
+ * Complete tool descriptor for discovery and invocation.
+ *
+ * Discovery uses: id, name, description, category
+ * Invocation uses: id, requiresConfirmation, invocationMode
+ */
+export interface MCPToolDescriptor {
+  /** Unique identifier (matches MCP tool name, e.g., 'cs_help') */
+  id: string
+  /** Human-readable name for display */
+  name: string
+  /** User-facing description (what it does, not how) */
+  description: string
+  /** Grouping category for UI organization */
+  category: ToolCategory
+  /** Whether user confirmation is required before execution */
+  requiresConfirmation: boolean
+  /** How the tool can be triggered */
+  invocationMode: ToolInvocationMode
+  /** Who can see this tool */
+  visibility: ToolVisibility
+}
+
+/**
+ * Response shape for tool discovery endpoint.
+ * Used by GET /api/capabilities/tools
+ *
+ * Transport-level type (HTTP API response).
+ * No timestamp - ephemeral, regenerated often.
+ */
+export interface ToolDiscoveryResponse {
+  /** Tools available to the current user */
+  tools: MCPToolDescriptor[]
+}
+
+/**
+ * Structured message part for protocol-level rendering.
+ *
+ * Conversation-level type (chat protocol part).
+ * Rendered atomically, not streamed char-by-char.
+ */
+export interface ToolListMessagePart {
+  type: 'tool-list'
+  tools: MCPToolDescriptor[]
+}