Standard capability types for AI agent tools — the lib.d.ts for Effectors.

Type System

@effectorhq/types provides a standard library of capability types — reusable type definitions for the inputs, outputs, and contexts that AI agent tools commonly work with. 40 types across three roles, grounded in real-world usage from 13,000+ analyzed tools.

Why Types for Agent Capabilities

TypeScript proved that adding types to an untyped ecosystem transforms it. Before TypeScript, JavaScript developers composed modules by convention and prayer. After TypeScript, composition became verifiable.

AI agent capabilities are in the pre-TypeScript era right now:

With effector types, compatibility is checked statically:

# Tool A: produces ReviewReport
[effector.interface]
output = "ReviewReport"

# Tool B: accepts ReviewReport
[effector.interface]
input = "ReviewReport"Copy

The composition checker knows these connect. It also knows that SecurityReport (a structural subtype of ReviewReport) would work too.

The Three Categories

Input Types (15 types)

What your capability accepts. Every input type defines required and optional fields:

Output Types (14 types)

What your capability produces:

Context Types (13 types)

Runtime environment your capability needs:

Structural Subtyping

Types use structural subtyping (like TypeScript, not like Java). Two types are compatible if their shapes match — no explicit inheritance required.

ReviewReport:    { findings, severity, summary }
SecurityReport:  { vulnerabilities, risk, summary, findings, severity, ... }

→ SecurityReport is a structural subtype of ReviewReport
→ Any Effector expecting ReviewReport will accept SecurityReportCopy

This means the ecosystem is open to extension without coordination. You define a new type that structurally matches an existing one, and it automatically composes with everything that existing type composes with.

Known subtype relations:

• SecurityReport → subtype of ReviewReport
• SlackMessage → subtype of Notification
• DiscordMessage → subtype of Notification

Compatibility Rules

1. Exact match           → precision 1.0
2. Alias resolution      → precision 0.95  (PlainText → String)
3. Subtype relation      → precision 0.9   (SecurityReport → ReviewReport)
4. Wildcard matching     → precision 0.8   (*Report matches ReviewReport)
5. Structural subtyping  → precision varies
6. Otherwise             → incompatibleCopy

Fields

Every type defines required and optional fields. For example, PullRequestRef:

• Required: number
• Optional: repo, provider, title, headBranch, baseBranch, url

Fields are the structural contract. When two types connect, the type checker verifies field compatibility.

Frequency

Every type includes a frequency score (0.0 to 1.0) derived from analysis of 13,000+ real-world AI tools. This grounds the type catalog in actual usage patterns:

• Discovery — sort search results by relevance
• Scaffolding — suggest likely types when creating new capabilities
• Ecosystem analysis — understand what the community builds

Relationship to Existing Standards

Using Types

In effector.toml

[effector.interface]
input = "CodeDiff"
output = "ReviewReport"
context = ["Repository", "GitHubCredentials"]Copy

Checking Types

# Validate types against the catalog
npx @effectorhq/core check-types .

# List all available types
npx @effectorhq/core typesCopy

Composition

# Check if two capabilities compose
npx @effectorhq/compose check ./capability-a ./capability-bCopy

Browse the Full Catalog

See every type with its fields, aliases, and relationships in the Type Catalog.