admin/AirCoding
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

P0-P8: Full V1.0.0 Alpha implementation + audit reports

Browse Source 
Implements 123 tasks across 9 phases (T-001..T-809) totaling 146 source files.

Monorepo (P0):
- 7-package Bun + Turborepo + TypeScript monorepo
- dependency-cruiser enforcing 7 forbidden edges + 5 deep-import rules

Contracts (P0):
- 16 type files (ids/error/event/runtime/ipc/task/worker-result/tool/artifact/evidence/project/provider/permission/ui/capability/platform)

Storage & Events (P1):
- DatabaseManager + MigrationRunner (19 tables, 22 indexes, 5 schema_meta seeds)
- 16 repositories (Repository<T,I,U> pattern, INV-1 status columns via EventStore.project only)
- EventSchemaRegistry (54 durable + 7 ephemeral), EventStore, EventBus, EventIngestor
- Project/Session/Artifact/Evidence stores + 8-step Recovery

Tools & Permission (P2):
- PathClassifier (8 categories), CommandRiskAnalyzer (10 categories), SecretRedactor
- PermissionEngine 6-layer evaluation (capability→profile→task_scope→risk→credential→user_prompt)
- ToolRegistry with 20+ tools across fs/shell/git/project/artifact/context/permission/doctor
- CapabilityManifestValidator + CapabilityRegistry

LLM & Context (P3):
- ModelConfigLoader, CapabilityMatrix, AnthropicCanonicalConverter
- AnthropicAdapter + OpenAICompatibleAdapter
- ProviderManager facade
- PromptLayerLoader (L0/L1/L3/L5), CompactionPolicy, ContextAssembler

Worker IPC & Scheduler (P4):
- WorkerProtocol (NDJSON), WorkerProcess (exit codes 0-5), WorkerManager (spawn/handshake)
- WorkerRuntime (INV-3: IPC only, no direct fs/shell/SQLite)
- 5 worker roles (Executor/Reviewer/Debugger/Compactor/ExperienceMiner)
- TaskGraph, WavePlanner, RetryPlanner, AgentMonitor, WorkspaceManager
- Scheduler (state machine), 8-step Recovery

C++ Toolchain (P5):
- DiagnosticParser, CppProjectDetector, CMakeConfigurator, CppBuilder
- CppTestRunner, CppcheckRunner, ClangdClient
- CppToolRegistrar + capability manifest

Projection & TUI (P6):
- ProjectionStore (hydrate/apply/snapshot/subscribe)
- TuiApp + 8 components (Session/Task/Agent/Tool/Diff/Evidence/Permission/Blocker/Hud)
- ProjectionClient in-process ref

Agents & Knowledge (P7):
- MainAgent, ArchitectureDesigner
- DebugKnowledgeStore + LearnedMemoryStore (single-writer, outbox model)
- Role integration wiring

CLI & Doctor & Release (P8):
- Logger + DeveloperLogEncryptor (AES-256-GCM)
- DoctorService (self_bootstrap first)
- RuntimeApp + ServiceRegistry
- 11 CLI commands: run/init/doctor/provider/resume/compact/history/session/restore/e2e/release
- CliEntrypoint + air<TODO>

Audit (in AirPlan/docs/):
- Deepseek开发阶段审计.md (97 findings)
- Opus开发阶段审计.md (140+ findings, 18 P0 blockers)
- MiniMaxM3开发阶段审计.md (18 P0 blockers, focuses on executability)
- AirPlan/TODO.md (technical debt + 42 TODOs by phase)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
AirCoding
2026-06-02 19:19:55 +08:00
parent 071283df8f
commit a773bac28c
179 changed files with 21855 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
packages/llm/package.json Executable file
View File

@@ -0,0 +1,22 @@
{
"name": "@aircoding/llm",
"version": "1.0.0-alpha.0",
"private": true,
"type": "module",
"main": "./src/index.ts",
"types": "./src/index.ts",
"exports": {
".": "./src/index.ts"
},
"scripts": {
"typecheck": "tsc --noEmit",
"build": "tsc --build",
"clean": "rm -rf dist tsconfig.tsbuildinfo"
},
"dependencies": {
"@aircoding/contracts": "workspace:*"
},
"devDependencies": {
"typescript": "^5.8.0"
}
}

233
packages/llm/src/CapabilityMatrix.ts Executable file
View File

@@ -0,0 +1,233 @@
/**
* CapabilityMatrixRegistry - Provider capability matrix lookup
*
* Implements DD §12.2.
* Holds ProviderCapabilityMatrix rows.
*
* @module packages/llm/src/CapabilityMatrix
*/
export interface ProviderCapability {
provider: string
model: string
max_tokens_output?: number
max_tokens_input?: number
supports_thinking?: boolean
supports_vision?: boolean
supports_tools?: boolean
supports_streaming?: boolean
supports_json_mode?: boolean
supports_temperature?: boolean
supports_top_p?: boolean
}
export interface ProviderCapabilityMatrix {
provider: string
model_pattern: string
capabilities: Omit<ProviderCapability, 'provider' | 'model'>
}
// Capability matrix - would be loaded from provider-capability-matrix-v1.md
const CAPABILITY_MATRIX: ProviderCapabilityMatrix[] = [
{
provider: 'anthropic',
model_pattern: '^claude-opus-4-.*',
capabilities: {
max_tokens_output: 200000,
max_tokens_input: 200000,
supports_thinking: true,
supports_vision: true,
supports_tools: true,
supports_streaming: true,
supports_json_mode: true,
supports_temperature: true,
supports_top_p: true
}
},
{
provider: 'anthropic',
model_pattern: '^claude-sonnet-4-.*',
capabilities: {
max_tokens_output: 200000,
max_tokens_input: 200000,
supports_thinking: true,
supports_vision: true,
supports_tools: true,
supports_streaming: true,
supports_json_mode: true,
supports_temperature: true,
supports_top_p: true
}
},
{
provider: 'anthropic',
model_pattern: '^claude-haiku-4-.*',
capabilities: {
max_tokens_output: 200000,
max_tokens_input: 200000,
supports_thinking: false,
supports_vision: true,
supports_tools: true,
supports_streaming: true,
supports_json_mode: true,
supports_temperature: true,
supports_top_p: true
}
},
{
provider: 'openai',
model_pattern: '^gpt-5-.*',
capabilities: {
max_tokens_output: 128000,
max_tokens_input: 128000,
supports_thinking: true,
supports_vision: true,
supports_tools: true,
supports_streaming: true,
supports_json_mode: true,
supports_temperature: true,
supports_top_p: true
}
},
{
provider: 'openai',
model_pattern: '^gpt-4[ot]-.*',
capabilities: {
max_tokens_output: 128000,
max_tokens_input: 128000,
supports_thinking: false,
supports_vision: true,
supports_tools: true,
supports_streaming: true,
supports_json_mode: true,
supports_temperature: true,
supports_top_p: true
}
},
{
provider: 'openai-compatible',
model_pattern: '.*',
capabilities: {
// Defaults for compatible providers - actual capability varies
max_tokens_output: 4096,
max_tokens_input: 128000,
supports_thinking: false,
supports_vision: false,
supports_tools: true,
supports_streaming: true,
supports_json_mode: true,
supports_temperature: true,
supports_top_p: true
}
},
{
provider: 'glm',
model_pattern: '^glm-5-.*',
capabilities: {
max_tokens_output: 128000,
max_tokens_input: 128000,
supports_thinking: true,
supports_vision: true,
supports_tools: true,
supports_streaming: true,
supports_json_mode: true,
supports_temperature: true,
supports_top_p: true
}
}
]
export class CapabilityMatrixRegistry {
private matrix: ProviderCapabilityMatrix[]
constructor(matrix?: ProviderCapabilityMatrix[]) {
this.matrix = matrix || CAPABILITY_MATRIX
}
/**
* Look up capabilities for a specific provider/model.
*/
lookup(provider: string, model: string): ProviderCapability | undefined {
// Find matching entry
for (const entry of this.matrix) {
if (entry.provider !== provider) continue
const regex = new RegExp(entry.model_pattern)
if (regex.test(model)) {
return {
provider,
model,
...entry.capabilities
}
}
}
return undefined
}
/**
* List all models for a provider.
*/
list_models(provider: string): string[] {
const models: string[] = []
for (const entry of this.matrix) {
if (entry.provider === provider) {
// Extract example model name from pattern
const example = entry.model_pattern.replace(/^\^|\$.*$/g, '')
models.push(example || entry.model_pattern)
}
}
return models
}
/**
* Check if a provider/model supports a specific capability.
*/
supports(provider: string, model: string, capability: keyof Omit<ProviderCapability, 'provider' | 'model'>): boolean {
const caps = this.lookup(provider, model)
if (!caps) return false
return caps[capability] === true
}
/**
* Get the best model for a set of requirements.
*/
find_best(
provider: string,
requirements: {
min_output_tokens?: number
supports_thinking?: boolean
supports_tools?: boolean
}
): string | undefined {
const entries = this.matrix.filter(e => e.provider === provider)
for (const entry of entries) {
const caps = entry.capabilities
if (requirements.min_output_tokens && (!caps.max_tokens_output || caps.max_tokens_output < requirements.min_output_tokens)) {
continue
}
if (requirements.supports_thinking && !caps.supports_thinking) {
continue
}
if (requirements.supports_tools && !caps.supports_tools) {
continue
}
// Return first matching model pattern
return entry.model_pattern.replace(/[\^$]/g, '')
}
return undefined
}
}
export function createCapabilityMatrixRegistry(): CapabilityMatrixRegistry {
return new CapabilityMatrixRegistry()
}

190
packages/llm/src/ModelConfigLoader.ts Executable file
View File

@@ -0,0 +1,190 @@
/**
* ModelConfigLoader - Loads model configuration from YAML files
*
* Implements DD §12.2.
* Loads global ~/.air/models.yaml + project config.
*
* @module packages/llm/src/ModelConfigLoader
*/
import { readFileSync, existsSync } from 'fs'
import { resolve, join } from 'path'
import { homedir } from 'os'
export interface ModelConfig {
provider: string
model: string
api_key?: string
base_url?: string
max_tokens?: number
temperature?: number
top_p?: number
}
export interface ModelConfigSet {
global?: Record<string, ModelConfig>
project?: Record<string, ModelConfig>
}
export interface ConfigLoadResult {
ok: boolean
configs?: ModelConfigSet
error?: string
}
const DEFAULT_CONFIG_PATH = join(homedir(), '.air', 'models.yaml')
export class ModelConfigLoader {
private global_config_path: string
private project_config_path?: string
constructor(global_path?: string, project_path?: string) {
this.global_config_path = global_path || DEFAULT_CONFIG_PATH
this.project_config_path = project_path
}
/**
* Load all model configurations.
*/
load(): ConfigLoadResult {
const configs: ModelConfigSet = {}
// Load global config
if (existsSync(this.global_config_path)) {
try {
const content = readFileSync(this.global_config_path, 'utf-8')
configs.global = this.parse_yaml(content)
} catch (error) {
return { ok: false, error: `Failed to load global config: ${error instanceof Error ? error.message : String(error)}` }
}
}
// Load project config if specified
if (this.project_config_path && existsSync(this.project_config_path)) {
try {
const content = readFileSync(this.project_config_path, 'utf-8')
configs.project = this.parse_yaml(content)
} catch (error) {
return { ok: false, error: `Failed to load project config: ${error instanceof Error ? error.message : String(error)}` }
}
}
return { ok: true, configs }
}
/**
* Get config for a specific model by name.
*/
get_model(name: string): ModelConfig | undefined {
const result = this.load()
if (!result.ok || !result.configs) return undefined
// Project config takes precedence over global
if (result.configs.project?.[name]) {
return result.configs.project[name]
}
return result.configs.global?.[name]
}
/**
* Validate required fields in a model config.
*/
validate(config: ModelConfig): { valid: boolean; error?: string } {
if (!config.provider) {
return { valid: false, error: 'provider is required' }
}
if (!config.model) {
return { valid: false, error: 'model is required' }
}
// Provider-specific validation
if (config.provider === 'anthropic') {
if (!config.api_key && !process.env.ANTHROPIC_API_KEY) {
// Warning, not error - might use default credentials
}
}
if (config.provider === 'openai' || config.provider === 'openai-compatible') {
if (!config.api_key && !process.env.OPENAI_API_KEY) {
// Warning
}
}
return { valid: true }
}
/**
* Simple YAML parser for model configs.
* In production, use a proper YAML library.
*/
private parse_yaml(content: string): Record<string, ModelConfig> {
const result: Record<string, ModelConfig> = {}
const lines = content.split('\n')
let current_key = ''
let current_config: Partial<ModelConfig> = {}
for (const line of lines) {
const trimmed = line.trim()
// Skip comments and empty lines
if (!trimmed || trimmed.startsWith('#')) continue
// Check for top-level key (model name)
if (trimmed.endsWith(':') && !trimmed.includes(' ')) {
// Save previous config
if (current_key && current_config.provider) {
result[current_key] = current_config as ModelConfig
}
current_key = trimmed.slice(0, -1)
current_config = {}
continue
}
// Parse key: value pairs
const colon_idx = trimmed.indexOf(':')
if (colon_idx > 0) {
const key = trimmed.slice(0, colon_idx).trim()
const value = trimmed.slice(colon_idx + 1).trim()
// Remove quotes from value
const clean_value = value.replace(/^["']|["']$/g, '')
switch (key) {
case 'provider':
current_config.provider = clean_value
break
case 'model':
current_config.model = clean_value
break
case 'api_key':
current_config.api_key = clean_value
break
case 'base_url':
current_config.base_url = clean_value
break
case 'max_tokens':
current_config.max_tokens = parseInt(clean_value, 10)
break
case 'temperature':
current_config.temperature = parseFloat(clean_value)
break
case 'top_p':
current_config.top_p = parseFloat(clean_value)
break
}
}
}
// Save last config
if (current_key && current_config.provider) {
result[current_key] = current_config as ModelConfig
}
return result
}
}
export function createModelConfigLoader(global_path?: string, project_path?: string): ModelConfigLoader {
return new ModelConfigLoader(global_path, project_path)
}

204
packages/llm/src/ProviderManager.ts Executable file
View File

@@ -0,0 +1,204 @@
/**
* ProviderManager - Unified facade for LLM providers
*
* Implements contracts §15; DD §12.1.
* INV-4: runtime calls llm only via this facade.
*
* @module packages/llm/src/ProviderManager
*/
// Local type definitions (contract types not yet finalized)
type CompleteOptions = { max_tokens?: number; temperature?: number; top_p?: number; system?: string }
type StreamEvent = { type: 'text' | 'thinking' | 'done'; content?: string; reason?: string }
type ModelRequirement = { model: string; provider?: string; min_output_tokens?: number; prefers_thinking?: boolean; requires_tools?: boolean }
type ModelAssignment = { provider: string; model: string; adapter: any; capabilities?: any }
import { ModelConfigLoader, createModelConfigLoader } from './ModelConfigLoader.js'
import { CapabilityMatrixRegistry, createCapabilityMatrixRegistry } from './CapabilityMatrix.js'
import { AnthropicAdapter, createAnthropicAdapter } from './adapters/AnthropicAdapter.js'
import { OpenAICompatibleAdapter, createOpenAICompatibleAdapter } from './adapters/OpenAICompatibleAdapter.js'
export interface ProviderManagerConfig {
config_loader?: ModelConfigLoader
capability_matrix?: CapabilityMatrixRegistry
}
export class ProviderManager {
private config_loader: ModelConfigLoader
private capability_matrix: CapabilityMatrixRegistry
private adapters: Map<string, ProviderAdapter> = new Map()
private current_adapter: ProviderAdapter | null = null
private current_model: string = ''
constructor(config: ProviderManagerConfig = {}) {
this.config_loader = config.config_loader || createModelConfigLoader()
this.capability_matrix = config.capability_matrix || createCapabilityMatrixRegistry()
// Initialize adapters
this.initialize_adapters()
}
/**
* Load configuration from files.
*/
load_config(): { ok: boolean; error?: string } {
const result = this.config_loader.load()
if (!result.ok) {
return { ok: false, error: result.error }
}
return { ok: true }
}
/**
* Select a model based on requirements.
* Returns a ModelAssignment.
*/
select_model(requirement: ModelRequirement): ModelAssignment {
// Try to find matching model in capability matrix
const best_model = this.capability_matrix.find_best(requirement.provider || 'anthropic', {
min_output_tokens: requirement.min_output_tokens,
supports_thinking: requirement.prefers_thinking,
supports_tools: requirement.requires_tools
})
const model = requirement.model || best_model || `${requirement.provider}-default`
// Get adapter for this provider
const adapter = this.get_or_create_adapter(requirement.provider || 'anthropic', model)
this.current_adapter = adapter
this.current_model = model
return {
provider: requirement.provider || 'anthropic',
model,
adapter,
capabilities: this.capability_matrix.lookup(requirement.provider || 'anthropic', model)
}
}
/**
* Complete a request with the current model.
*/
async complete(
messages: unknown[],
assignment: ModelAssignment,
options: CompleteOptions = {}
): Promise<{ content: string; usage?: { input_tokens: number; output_tokens: number } }> {
const adapter = assignment.adapter || this.current_adapter
if (!adapter) {
throw new Error('No adapter selected. Call select_model first.')
}
return adapter.complete(messages as any, { model: assignment.model }, options)
}
/**
* Stream a completion request.
*/
async *stream_complete(
messages: unknown[],
assignment: ModelAssignment,
options: CompleteOptions = {}
): AsyncGenerator<StreamEvent> {
const adapter = assignment.adapter || this.current_adapter
if (!adapter) {
throw new Error('No adapter selected. Call select_model first.')
}
yield* adapter.stream_complete(messages as any, { model: assignment.model }, options)
}
/**
* Get an adapter for a specific provider.
*/
adapter_for(provider: string, model: string): ProviderAdapter {
return this.get_or_create_adapter(provider, model)
}
/**
* Get current adapter.
*/
get_current_adapter(): ProviderAdapter | null {
return this.current_adapter
}
/**
* Get current model.
*/
get_current_model(): string {
return this.current_model
}
// ============================================================================
// Private helpers
// ============================================================================
private initialize_adapters(): void {
// Create default adapters
const anthropic = createAnthropicAdapter()
this.adapters.set('anthropic', anthropic)
// Check for OpenAI-compatible providers in config
const config = this.config_loader.load()
if (config.ok && config.configs?.global) {
for (const [name, model_config] of Object.entries(config.configs.global)) {
if (model_config.provider === 'openai-compatible' && model_config.base_url) {
const adapter = createOpenAICompatibleAdapter({
base_url: model_config.base_url,
model: model_config.model,
api_key: model_config.api_key
})
this.adapters.set(name, adapter)
}
}
}
}
private get_or_create_adapter(provider: string, model: string): ProviderAdapter {
// Check if we already have an adapter for this provider
const existing = this.adapters.get(provider)
if (existing) {
return existing
}
// Create new adapter based on provider
let adapter: ProviderAdapter
if (provider === 'anthropic') {
adapter = createAnthropicAdapter()
} else {
// Check config for OpenAI-compatible
const model_config = this.config_loader.get_model(`${provider}-${model}`)
if (model_config?.base_url) {
adapter = createOpenAICompatibleAdapter({
base_url: model_config.base_url,
model: model_config.model,
api_key: model_config.api_key
})
} else {
// Default to OpenAI-compatible with default settings
adapter = createOpenAICompatibleAdapter({
base_url: process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1',
model: model
})
}
}
this.adapters.set(provider, adapter)
return adapter
}
}
export function createProviderManager(config?: ProviderManagerConfig): ProviderManager {
return new ProviderManager(config)
}
// Export facade as default instance
let default_instance: ProviderManager | undefined
export function get_provider_manager(): ProviderManager {
if (!default_instance) {
default_instance = createProviderManager()
}
return default_instance
}

233
packages/llm/src/adapters/AnthropicAdapter.ts Executable file
View File

@@ -0,0 +1,233 @@
/**
* AnthropicAdapter - Provider adapter for Anthropic API
*
* Implements ProviderAdapter contract (contracts §15); DD §12.2.
*
* @module packages/llm/src/adapters/AnthropicAdapter
*/
import type { CanonicalMessage } from '../canonical/AnthropicCanonical.js'
import { AnthropicCanonicalConverter } from '../canonical/AnthropicCanonical.js'
// Local type definitions (contract types not yet finalized)
type CompleteOptions = { max_tokens?: number; temperature?: number; top_p?: number; system?: string }
type StreamEvent = { type: 'text' | 'thinking' | 'done'; content?: string; reason?: string }
type ModelRequirement = { model: string; provider?: string; min_output_tokens?: number; prefers_thinking?: boolean; requires_tools?: boolean }
export interface AnthropicConfig {
api_key?: string
base_url?: string
max_retries?: number
timeout?: number
}
// Provider stream events
export type AnthropicStreamEvent =
| { type: 'content_block_start'; index: number; block_type: string }
| { type: 'content_block_delta'; index: number; delta: { type: string; text?: string; thinking?: string } }
| { type: 'content_block_stop'; index: number }
| { type: 'message_start'; message: { id: string; type: string; role: string; content: unknown[] } }
| { type: 'message_delta'; delta: { stop_reason?: string; usage?: { output_tokens: number } } }
| { type: 'message_stop' }
export class AnthropicAdapter {
private api_key: string
private base_url: string
private max_retries: number
private timeout: number
private converter: AnthropicCanonicalConverter
constructor(config: AnthropicConfig = {}) {
this.api_key = config.api_key || process.env.ANTHROPIC_API_KEY || ''
this.base_url = config.base_url || process.env.ANTHROPIC_BASE_URL || 'https://api.anthropic.com'
this.max_retries = config.max_retries || 3
this.timeout = config.timeout || 60000
this.converter = new AnthropicCanonicalConverter()
}
async list_models(): Promise<string[]> {
// Anthropic doesn't have a list_models API, return known models
return [
'claude-opus-4-7-20251119',
'claude-sonnet-4-6-20250501',
'claude-haiku-4-5-20251001'
]
}
async validate_model(model: string): Promise<{ valid: boolean; error?: string }> {
const known = await this.list_models()
// Allow any model that looks like a Claude model
if (model.startsWith('claude-')) {
return { valid: true }
}
// Or check known list
if (known.includes(model)) {
return { valid: true }
}
return { valid: false, error: `Unknown model: ${model}` }
}
async complete(
messages: CanonicalMessage[],
requirement: ModelRequirement,
options: CompleteOptions = {}
): Promise<{ content: string; usage?: { input_tokens: number; output_tokens: number } }> {
const { canonical, report } = this.converter.from_provider('anthropic', messages as unknown[])
if (!report.ok) {
throw new Error(`Conversion failed: ${report.warnings.join(', ')}`)
}
const response = await this.make_request({
model: requirement.model,
messages: canonical.map(m => ({
role: m.role,
content: m.content.map(c => {
if (c.type === 'text') return { type: 'text', text: c.text }
if (c.type === 'thinking') return { type: 'thinking', thinking: c.thinking }
if (c.type === 'tool_use') return { type: 'tool_use', id: c.id, name: c.name, input: c.input }
return { type: 'text', text: '[tool]' }
})
})),
max_tokens: options.max_tokens || 4096,
temperature: options.temperature,
top_p: options.top_p,
system: options.system,
stream: false
})
// Extract content from response
const content = this.extract_content(response)
const usage = response.usage ? { input_tokens: response.usage.input_tokens, output_tokens: response.usage.output_tokens } : undefined
return { content, usage }
}
async *stream_complete(
messages: CanonicalMessage[],
requirement: ModelRequirement,
options: CompleteOptions = {}
): AsyncGenerator<StreamEvent> {
const { canonical, report } = this.converter.from_provider('anthropic', messages as unknown[])
if (!report.ok) {
throw new Error(`Conversion failed: ${report.warnings.join(', ')}`)
}
const response = await this.make_request({
model: requirement.model,
messages: canonical.map(m => ({
role: m.role,
content: m.content.map(c => {
if (c.type === 'text') return { type: 'text', text: c.text }
if (c.type === 'thinking') return { type: 'thinking', thinking: c.thinking }
if (c.type === 'tool_use') return { type: 'tool_use', id: c.id, name: c.name, input: c.input }
return { type: 'text', text: '[tool]' }
})
})),
max_tokens: options.max_tokens || 4096,
temperature: options.temperature,
top_p: options.top_p,
system: options.system,
stream: true
})
// Parse streaming response
const reader = response.body?.getReader()
if (!reader) {
throw new Error('No response body')
}
const decoder = new TextDecoder()
let buffer = ''
while (true) {
const { done, value } = await reader.read()
if (done) break
buffer += decoder.decode(value, { stream: true })
const lines = buffer.split('\n')
buffer = lines.pop() || ''
for (const line of lines) {
if (!line.trim() || !line.startsWith('data: ')) continue
const data = line.slice(6)
if (data === '[DONE]') continue
try {
const event = JSON.parse(data) as AnthropicStreamEvent
yield this.normalize_stream_event(event)
} catch {
// Skip invalid JSON
}
}
}
}
async count_tokens(text: string): Promise<number> {
// Simple estimation - in production use proper tokenization
return Math.ceil(text.length / 4)
}
// ============================================================================
// Private helpers
// ============================================================================
private async make_request(body: Record<string, unknown>): Promise<Record<string, unknown>> {
const url = `${this.base_url}/v1/messages`
const response = await fetch(url, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-api-key': this.api_key,
'anthropic-version': '2023-06-01'
},
body: JSON.stringify(body)
})
if (!response.ok) {
const error = await response.text()
throw new Error(`Anthropic API error: ${response.status} - ${error}`)
}
return response.json() as Promise<Record<string, unknown>>
}
private extract_content(response: Record<string, unknown>): string {
const content = response.content as Array<{ type: string; text?: string }> | undefined
if (!content) return ''
return content
.filter((b) => b.type === 'text')
.map((b) => b.text || '')
.join('')
}
private normalize_stream_event(event: AnthropicStreamEvent): StreamEvent {
switch (event.type) {
case 'content_block_delta':
if (event.delta.type === 'text_delta') {
return { type: 'text', content: event.delta.text || '' }
}
if (event.delta.type === 'thinking_delta') {
return { type: 'thinking', content: event.delta.thinking || '' }
}
return { type: 'text', content: '' }
case 'message_delta':
if (event.delta.stop_reason) {
return { type: 'done', reason: event.delta.stop_reason }
}
return { type: 'text', content: '' }
default:
return { type: 'text', content: '' }
}
}
}
export function createAnthropicAdapter(config?: AnthropicConfig): AnthropicAdapter {
return new AnthropicAdapter(config)
}

193
packages/llm/src/adapters/OpenAICompatibleAdapter.ts Executable file
View File

@@ -0,0 +1,193 @@
/**
* OpenAICompatibleAdapter - Provider adapter for OpenAI-compatible APIs
*
* Implements ProviderAdapter; uses AnthropicCanonicalConverter.
*
* @module packages/llm/src/adapters/OpenAICompatibleAdapter
*/
import type { CanonicalMessage } from '../canonical/AnthropicCanonical.js'
import { AnthropicCanonicalConverter } from '../canonical/AnthropicCanonical.js'
// Local type definitions (contract types not yet finalized)
type CompleteOptions = { max_tokens?: number; temperature?: number; top_p?: number; system?: string }
type StreamEvent = { type: 'text' | 'thinking' | 'done'; content?: string; reason?: string }
export interface OpenAICompatibleConfig {
api_key?: string
base_url: string
model: string
max_retries?: number
timeout?: number
}
export class OpenAICompatibleAdapter {
private api_key: string
private base_url: string
private model: string
private max_retries: number
private timeout: number
private converter: AnthropicCanonicalConverter
constructor(config: OpenAICompatibleConfig) {
this.api_key = config.api_key || process.env.OPENAI_API_KEY || 'dummy'
this.base_url = config.base_url
this.model = config.model
this.max_retries = config.max_retries || 3
this.timeout = config.timeout || 60000
this.converter = new AnthropicCanonicalConverter()
}
async list_models(): Promise<string[]> {
// Try to fetch model list, fallback to default
try {
const response = await fetch(`${this.base_url}/v1/models`, {
headers: { Authorization: `Bearer ${this.api_key}` }
})
if (response.ok) {
const data = await response.json() as { data: Array<{ id: string }> }
return data.data.map(m => m.id)
}
} catch {
// Ignore
}
return [this.model]
}
async validate_model(model: string): Promise<{ valid: boolean; error?: string }> {
const known = await this.list_models()
if (known.includes(model)) {
return { valid: true }
}
// Allow unknown models - might be valid
return { valid: true }
}
async complete(
messages: CanonicalMessage[],
_requirement: { model: string },
options: CompleteOptions = {}
): Promise<{ content: string; usage?: { input_tokens: number; output_tokens: number } }> {
// Convert to OpenAI format
const openai_messages = messages.map(m => ({
role: m.role,
content: m.content.map(c => {
if (c.type === 'text') return { type: 'text', text: c.text }
if (c.type === 'tool_use') return { type: 'tool_use', id: c.id, name: c.name, input: c.input }
return { type: 'text', text: '' }
})
}))
const response = await this.make_request({
model: this.model,
messages: openai_messages,
max_tokens: options.max_tokens || 4096,
temperature: options.temperature,
top_p: options.top_p,
stream: false
})
const content = (response.choices?.[0]?.message?.content as string) || ''
const usage = response.usage ? { input_tokens: response.usage.prompt_tokens, output_tokens: response.usage.completion_tokens } : undefined
return { content, usage }
}
async *stream_complete(
messages: CanonicalMessage[],
_requirement: { model: string },
options: CompleteOptions = {}
): AsyncGenerator<StreamEvent> {
const openai_messages = messages.map(m => ({
role: m.role,
content: m.content.map(c => {
if (c.type === 'text') return { type: 'text', text: c.text }
return { type: 'text', text: '' }
})
}))
const response = await this.make_request({
model: this.model,
messages: openai_messages,
max_tokens: options.max_tokens || 4096,
temperature: options.temperature,
top_p: options.top_p,
stream: true
})
const reader = response.body?.getReader()
if (!reader) {
throw new Error('No response body')
}
const decoder = new TextDecoder()
let buffer = ''
while (true) {
const { done, value } = await reader.read()
if (done) break
buffer += decoder.decode(value, { stream: true })
const lines = buffer.split('\n')
buffer = lines.pop() || ''
for (const line of lines) {
if (!line.trim() || !line.startsWith('data: ')) continue
const data = line.slice(6)
if (data === '[DONE]') {
yield { type: 'done', reason: 'stop' }
return
}
try {
const event = JSON.parse(data)
const choice = event.choices?.[0]
if (!choice) continue
if (choice.delta?.content) {
yield { type: 'text', content: choice.delta.content }
}
if (choice.finish_reason) {
yield { type: 'done', reason: choice.finish_reason }
}
} catch {
// Skip
}
}
}
}
async count_tokens(text: string): Promise<number> {
// Simple estimation
return Math.ceil(text.length / 4)
}
private async make_request(body: Record<string, unknown>): Promise<{ ok: boolean; status: number; body?: { getReader(): { read(): Promise<{ done: boolean; value: Uint8Array }> }; choices?: Array<{ message?: { content: string }; delta?: { content: string }; finish_reason?: string }>; usage?: { prompt_tokens: number; completion_tokens: number } } }> {
const response = await fetch(`${this.base_url}/v1/chat/completions`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${this.api_key}`
},
body: JSON.stringify(body)
})
if (!response.ok) {
const error = await response.text()
throw new Error(`OpenAI-compatible API error: ${response.status} - ${error}`)
}
// Handle streaming vs non-streaming
const is_streaming = body.stream === true
if (is_streaming) {
return { ok: true, status: 200, body: response.body as any }
}
return { ok: true, status: 200, body: await response.json() as any }
}
}
export function createOpenAICompatibleAdapter(config: OpenAICompatibleConfig): OpenAICompatibleAdapter {
return new OpenAICompatibleAdapter(config)
}

249
packages/llm/src/canonical/AnthropicCanonical.ts Executable file
View File

@@ -0,0 +1,249 @@
/**
* AnthropicCanonicalConverter - Converts between provider formats and Anthropic-canonical format
*
* Implements DD §12.2; Anthropic-canonical internal format.
* Must not silently drop semantic prompt/tool info (contracts §23).
*
* @module packages/llm/src/canonical/AnthropicCanonical
*/
// Canonical types are defined locally rather than imported from contracts
// to avoid circular dependencies and allow provider-specific extensions.
// =============================================================================
// Canonical Types (Anthropic-canonical internal format)
// =============================================================================
export interface CanonicalMessage {
role: 'user' | 'assistant' | 'system'
content: CanonicalContent[]
}
export type CanonicalContent = CanonicalText | CanonicalThinking | CanonicalToolUse | CanonicalToolResult
export interface CanonicalText {
type: 'text'
text: string
}
export interface CanonicalThinking {
type: 'thinking'
thinking: string
signature?: string
}
export interface CanonicalToolUse {
type: 'tool_use'
id: string
name: string
input: Record<string, unknown>
}
export interface CanonicalToolResult {
type: 'tool_result'
tool_use_id: string
content: string
is_error?: boolean
}
// =============================================================================
// Conversion Report
// =============================================================================
export interface ConversionReport {
ok: boolean
dropped_fields: string[]
warnings: string[]
input_tokens?: number
output_tokens?: number
}
// =============================================================================
// AnthropicCanonicalConverter
// =============================================================================
export class AnthropicCanonicalConverter {
/**
* Convert from provider format to canonical format.
* Provider format varies - this handles generic conversion.
*/
from_provider(provider: string, messages: unknown[]): { canonical: CanonicalMessage[]; report: ConversionReport } {
const dropped_fields: string[] = []
const warnings: string[] = []
const canonical: CanonicalMessage[] = messages.map(msg => {
if (typeof msg !== 'object' || msg === null) {
warnings.push('Skipping non-object message')
return { role: 'user' as const, content: [] }
}
const m = msg as Record<string, unknown>
const role = this.normalize_role(String(m.role || 'user'))
const content = this.convert_content(m.content, dropped_fields, warnings)
return { role, content }
})
return {
canonical,
report: { ok: true, dropped_fields, warnings }
}
}
/**
* Convert from canonical format to provider format.
*/
to_provider(provider: string, canonical: CanonicalMessage[]): { messages: unknown[]; report: ConversionReport } {
const dropped_fields: string[] = []
const warnings: string[] = []
const messages = canonical.map(msg => {
const content = this.convert_content_to_provider(msg.content, provider, dropped_fields, warnings)
return { role: msg.role, content }
})
return {
messages,
report: { ok: true, dropped_fields, warnings }
}
}
/**
* Round-trip test: canonical → provider → canonical
*/
roundtrip_test(provider: string, canonical: CanonicalMessage[]): { ok: boolean; loss_detected: boolean; report: ConversionReport } {
const to_provider_result = this.to_provider(provider, canonical)
const back_to_canonical = this.from_provider(provider, to_provider_result.messages)
// Check for loss
const original_json = JSON.stringify(canonical)
const back_json = JSON.stringify(back_to_canonical.canonical)
const loss_detected = original_json !== back_json
return {
ok: !loss_detected,
loss_detected,
report: {
ok: !loss_detected,
dropped_fields: [...to_provider_result.report.dropped_fields, ...back_to_canonical.report.dropped_fields],
warnings: [...to_provider_result.report.warnings, ...back_to_canonical.report.warnings]
}
}
}
// ============================================================================
// Private helpers
// ============================================================================
private normalize_role(role: string): 'user' | 'assistant' | 'system' {
const lower = role.toLowerCase()
if (lower === 'user' || lower === 'human') return 'user'
if (lower === 'assistant' || lower === 'ai' || lower === 'assistant') return 'assistant'
return 'system'
}
private convert_content(content: unknown, dropped: string[], warnings: string[]): CanonicalContent[] {
if (!content) return []
// Handle string content (simple case)
if (typeof content === 'string') {
return [{ type: 'text', text: content }]
}
// Handle array content
if (Array.isArray(content)) {
return content.map(c => this.convert_single_content(c, dropped, warnings)).filter((c): c is CanonicalContent => c !== null)
}
// Handle object content
if (typeof content === 'object') {
return [this.convert_single_content(content, dropped, warnings)].filter((c): c is CanonicalContent => c !== null)
}
warnings.push(`Unknown content type: ${typeof content}`)
return []
}
private convert_single_content(item: unknown, dropped: string[], warnings: string[]): CanonicalContent | null {
if (typeof item !== 'object' || item === null) {
return null
}
const obj = item as Record<string, unknown>
const type = String(obj.type || 'text')
switch (type) {
case 'text':
return { type: 'text', text: String(obj.text || '') }
case 'thinking':
if (!obj.thinking) {
warnings.push('Thinking block missing thinking field')
return null
}
return { type: 'thinking', thinking: String(obj.thinking), signature: obj.signature ? String(obj.signature) : undefined }
case 'tool_use':
if (!obj.id || !obj.name) {
warnings.push('ToolUse block missing id or name')
return null
}
return { type: 'tool_use', id: String(obj.id), name: String(obj.name), input: (obj.input as Record<string, unknown>) || {} }
case 'tool_result':
if (!obj.tool_use_id && !obj.id) {
warnings.push('ToolResult missing tool_use_id')
return null
}
return { type: 'tool_result', tool_use_id: String(obj.tool_use_id || obj.id), content: String(obj.content || ''), is_error: Boolean(obj.is_error) }
default:
// Unknown type - check if it's a text-like object
if (obj.text || obj.content) {
return { type: 'text', text: String(obj.text || obj.content || '') }
}
dropped.push(`Unknown content type: ${type}`)
return null
}
}
private convert_content_to_provider(content: CanonicalContent[], provider: string, dropped: string[], warnings: string[]): unknown[] {
// Convert canonical content to provider-specific format
if (provider === 'anthropic') {
// Anthropic native format
return content.map(c => {
switch (c.type) {
case 'text':
return { type: 'text', text: c.text }
case 'thinking':
return { type: 'thinking', thinking: c.thinking, signature: c.signature }
case 'tool_use':
return { type: 'tool_use', id: c.id, name: c.name, input: c.input }
case 'tool_result':
return { type: 'tool_result', tool_use_id: c.tool_use_id, content: c.content, is_error: c.is_error }
}
})
}
// OpenAI-compatible format
return content.map(c => {
switch (c.type) {
case 'text':
return { type: 'text', text: c.text }
case 'thinking':
dropped.push('thinking (not supported in OpenAI format)')
return { type: 'text', text: `[Thinking: ${c.thinking}]` }
case 'tool_use':
return { type: 'tool_use', id: c.id, name: c.name, input: c.input }
case 'tool_result':
return { tool_call_id: c.tool_use_id, content: c.content }
}
})
}
}
export function createAnthropicCanonicalConverter(): AnthropicCanonicalConverter {
return new AnthropicCanonicalConverter()
}

24
packages/llm/src/index.ts Executable file
View File

@@ -0,0 +1,24 @@
/**
* LLM package — Provider adapters and model management
*
* INV-4: runtime calls llm only via ProviderManager facade.
* @module packages/llm
*/
export { ModelConfigLoader, createModelConfigLoader } from './ModelConfigLoader.js'
export type { ModelConfig, ModelConfigSet, ConfigLoadResult } from './ModelConfigLoader.js'
export { CapabilityMatrixRegistry, createCapabilityMatrixRegistry } from './CapabilityMatrix.js'
export type { ProviderCapability, ProviderCapabilityMatrix } from './CapabilityMatrix.js'
export { ProviderManager, createProviderManager, get_provider_manager } from './ProviderManager.js'
export type { ProviderManagerConfig } from './ProviderManager.js'
export { AnthropicCanonicalConverter, createAnthropicCanonicalConverter } from './canonical/AnthropicCanonical.js'
export type { CanonicalMessage, CanonicalContent, ConversionReport } from './canonical/AnthropicCanonical.js'
export { AnthropicAdapter, createAnthropicAdapter } from './adapters/AnthropicAdapter.js'
export type { AnthropicConfig } from './adapters/AnthropicAdapter.js'
export { OpenAICompatibleAdapter, createOpenAICompatibleAdapter } from './adapters/OpenAICompatibleAdapter.js'
export type { OpenAICompatibleConfig } from './adapters/OpenAICompatibleAdapter.js'

11
packages/llm/tsconfig.json Executable file
View File

@@ -0,0 +1,11 @@
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"outDir": "./dist",
"rootDir": "./src"
},
"include": ["src"],
"references": [
{ "path": "../contracts" }
]
}