AirCoding/packages/contracts/src/capability.ts

// contracts §18 — Capability Contracts
// File: capability.ts — CapabilityManifestV1, ValidationResult, CapabilityRegistry, trust levels
// Implements: interface-contracts-v1.md §18

import type { CapabilityID, JsonSchema, JsonObject } from "./ids.js"
import type { ToolCategory } from "./tool.js"
import type { ToolPermissionSpec } from "./permission.js"
import type { ToolRegistry } from "./tool.js"

// =============================================================================
// contracts §18 — Capability Contracts
// =============================================================================

/**
 * Trust levels for capabilities, ordered from most trusted to least trusted.
 * Trust affects default enablement/prompt posture but never bypasses
 * ToolRegistry or PermissionEngine.
 */
export type CapabilityTrustLevel =
  | "built_in"           // Core AirCoding capabilities, always trusted
  | "project_local"      // Project-scoped capabilities, trusted within project
  | "user_installed"     // User-installed capabilities, moderate trust
  | "verified_publisher" // Third-party from verified publishers
  | "untrusted"          // Unverified third-party capabilities

export interface CapabilityToolSpec {
  name: string
  version: number
  category: ToolCategory
  description: string
  input_schema: JsonSchema
  output_schema: JsonSchema
  streaming?: boolean
  permissions: ToolPermissionSpec
}

export interface CapabilityManifestV1 {
  schema_version: 1  // Must be exactly 1 per DoD
  capability_id: CapabilityID
  display_name: string
  version: string
  description: string
  publisher?: string
  source: JsonObject
  trust_level: CapabilityTrustLevel
  tools: CapabilityToolSpec[]
  dependencies?: JsonObject[]
  permissions: JsonObject
  events?: {
    produced?: string[]
    consumed?: string[]
  }
  artifact_types?: string[]
  config_schema?: JsonSchema
  entrypoint?: JsonObject
}

export interface ValidationResult {
  ok: boolean
  errors: string[]
  warnings: string[]
}

export interface CapabilityRegistry {
  discover(): Promise<CapabilityManifestV1[]>
  validate(manifest: CapabilityManifestV1): Promise<ValidationResult>
  enable(capability_id: CapabilityID): Promise<void>
  disable(capability_id: CapabilityID): Promise<void>
  register_tools(tool_registry: ToolRegistry): Promise<void>
}