Reflect Metadata Injection

/reflect-metadata-injection

When to Use

• Build lightweight dependency injection containers for agent service registries
• Attach metadata to classes at decoration time for runtime introspection
• Auto-wire agent dependencies without explicit factory functions
• Implement decorators that record audit trails or capability declarations

Do NOT use for

• Simple config injection (use environment variables or [[cli-config-persistence]])
• Environments where experimentalDecorators is not enabled

tsconfig requirements

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata":  true
  }
}

Core metadata API

import 'reflect-metadata'

// Set metadata on a class
Reflect.defineMetadata('role', 'executor', MyClass)

// Get metadata
const role = Reflect.getMetadata('role', MyClass)  // → 'executor'

// Check existence
Reflect.hasMetadata('role', MyClass)  // → true

// List all keys on a target
Reflect.getMetadataKeys(MyClass)  // → ['role', 'design:type', ...]

// Delete
Reflect.deleteMetadata('role', MyClass)

Injectable decorator + DI container

import 'reflect-metadata'

const INJECTABLE_KEY = Symbol('injectable')
const registry = new Map<Function, unknown>()

// Decorator: mark class as injectable
function Injectable(): ClassDecorator {
  return (target) => {
    Reflect.defineMetadata(INJECTABLE_KEY, true, target)
  }
}

// Decorator: declare dependency token
function Inject(token: symbol): ParameterDecorator {
  return (target, _key, index) => {
    const tokens = Reflect.getMetadata('inject:tokens', target) ?? []
    tokens[index] = token
    Reflect.defineMetadata('inject:tokens', tokens, target)
  }
}

// Container: resolve constructor + inject dependencies
function resolve<T>(cls: new (...args: any[]) => T): T {
  if (!Reflect.getMetadata(INJECTABLE_KEY, cls)) {
    throw new Error(`[di] ${cls.name} is not @Injectable`)
  }

  const tokens: symbol[] = Reflect.getMetadata('inject:tokens', cls) ?? []
  const args = tokens.map(tok => registry.get(tok))
  return new cls(...args)
}

// Usage:
const DB_TOKEN = Symbol('db')
registry.set(DB_TOKEN, { query: async (sql: string) => [] })

@Injectable()
class AgentService {
  constructor(@Inject(DB_TOKEN) private db: any) {}
  async listTasks() { return this.db.query('SELECT * FROM tasks') }
}

const svc = resolve(AgentService)

Read design:paramtypes (emitDecoratorMetadata)

@Injectable()
class OrderService {
  constructor(
    private db:     DatabaseService,
    private logger: LoggerService,
  ) {}
}

// After @Injectable() fires, TypeScript emits:
const types = Reflect.getMetadata('design:paramtypes', OrderService)
// → [DatabaseService, LoggerService]
// Allows container to auto-resolve by constructor type

Audit capability decorator

function Capability(name: string): MethodDecorator {
  return (target, key) => {
    const caps: string[] = Reflect.getMetadata('capabilities', target) ?? []
    caps.push(name)
    Reflect.defineMetadata('capabilities', caps, target)
  }
}

class SandboxAgent {
  @Capability('file-read')
  readFile(path: string) { /* ... */ }

  @Capability('network-fetch')
  fetch(url: string)     { /* ... */ }
}

const caps = Reflect.getMetadata('capabilities', SandboxAgent.prototype)
// → ['file-read', 'network-fetch']
// yamtam can gate these against the agent's declared capability set

Anti-Fake-Pass Checklist

❌ Missing `import 'reflect-metadata'` at entry point → Reflect.defineMetadata is undefined
❌ emitDecoratorMetadata: false → design:paramtypes always undefined, DI auto-wiring fails
❌ Metadata defined on instance vs prototype → Reflect.getMetadata(key, instance) ≠ Reflect.getMetadata(key, Class.prototype)
❌ Symbol tokens not shared between Inject() and registry → tokens don't match, injection returns undefined
❌ resolve() before registry.set() → dependency is undefined, constructor receives undefined silently
❌ Circular dependencies → resolve() hangs in infinite recursion without detection