List package contents #14

New issue

Open

opened 2026-01-05 21:13:23 +00:00 by mprihoda · 0 comments

mprihoda commented

2026-01-05 21:13:23 +00:00

(Migrated from github.com)

Problem

Agent knows it needs something from cats.effect but doesn't know all available classes/traits/objects. Currently must either:

Guess class names
Fetch docs for classes one by one
Ask the user

Proposed Solution

New Tool: `list_package`

{
  "name": "list_package",
  "description": "List all public types in a package",
  "input": {
    "coordinates": "Maven/Coursier coordinates",
    "packageName": "Package to list",
    "scalaVersion": "optional, default '3'"
  }
}

Example:

list_package("org.typelevel::cats-effect:3.5.4", "cats.effect")

Returns:

{
  "package": "cats.effect",
  "types": [
    {"name": "IO", "kind": "class", "description": "Primary effect type"},
    {"name": "IOApp", "kind": "trait", "description": "Application entry point"},
    {"name": "Resource", "kind": "class", "description": "Resource management"},
    {"name": "Ref", "kind": "trait", "description": "Mutable reference"},
    {"name": "Deferred", "kind": "trait", "description": "One-shot semantic"}
  ],
  "subpackages": ["kernel", "std", "unsafe"]
}

Implementation

Parse Javadoc/Scaladoc JAR's package-summary.html or index.html
Alternatively: Use TASTy for Scala 3 artifacts (more accurate)
Could extract brief descriptions from first sentence of class docs

Value for Agent

Quickly understand what's available in a package
Find the right class without guessing
Discover subpackages for deeper exploration

Acceptance Criteria

List all public classes/traits/objects in a package
Include kind (class, trait, object, enum)
Include brief description (first sentence)
List subpackages
Work for both Java and Scala artifacts

## Problem Agent knows it needs something from `cats.effect` but doesn't know all available classes/traits/objects. Currently must either: - Guess class names - Fetch docs for classes one by one - Ask the user ## Proposed Solution ### New Tool: `list_package` ```json { "name": "list_package", "description": "List all public types in a package", "input": { "coordinates": "Maven/Coursier coordinates", "packageName": "Package to list", "scalaVersion": "optional, default '3'" } } ``` **Example:** ``` list_package("org.typelevel::cats-effect:3.5.4", "cats.effect") ``` **Returns:** ```json { "package": "cats.effect", "types": [ {"name": "IO", "kind": "class", "description": "Primary effect type"}, {"name": "IOApp", "kind": "trait", "description": "Application entry point"}, {"name": "Resource", "kind": "class", "description": "Resource management"}, {"name": "Ref", "kind": "trait", "description": "Mutable reference"}, {"name": "Deferred", "kind": "trait", "description": "One-shot semantic"} ], "subpackages": ["kernel", "std", "unsafe"] } ``` ## Implementation - Parse Javadoc/Scaladoc JAR's `package-summary.html` or `index.html` - Alternatively: Use TASTy for Scala 3 artifacts (more accurate) - Could extract brief descriptions from first sentence of class docs ## Value for Agent - Quickly understand what's available in a package - Find the right class without guessing - Discover subpackages for deeper exploration ## Acceptance Criteria - [ ] List all public classes/traits/objects in a package - [ ] Include kind (class, trait, object, enum) - [ ] Include brief description (first sentence) - [ ] List subpackages - [ ] Work for both Java and Scala artifacts