@codmir/agent-contracts

Shared TypeScript contracts and Zod schemas for the Codmir agent intelligence system.

Installation

pnpm add @codmir/agent-contracts

Modules

Session Contracts (session.ts)

Core session types for the session engine:

import { 
  SessionState, 
  SessionResidueMinimum,
  SessionStatus 
} from '@codmir/agent-contracts';

// Create session state
const session: SessionState = {
  sessionId: 'sess_123',
  status: 'executing',
  projectId: 'proj_456',
  intent: 'Analyze authentication flow',
  participants: [
    { id: 'user_1', type: 'human', name: 'Developer', joinedAt: new Date().toISOString() },
    { id: 'agent_1', type: 'orchestrator', name: 'Orchestrator', joinedAt: new Date().toISOString() }
  ],
  createdAt: new Date().toISOString()
};

// Validate with Zod
SessionStateSchema.parse(session);

Distillation Contracts (distillation.ts)

Types for the three-stage distillation pipeline:

Stage 1: Extraction (during session)

import { SessionExtraction, Decision, Risk } from '@codmir/agent-contracts';

const extraction: SessionExtraction = {
  sessionId: 'sess_123',
  extractedAt: new Date().toISOString(),
  decisions: [{
    type: 'architecture',
    content: 'Switch to JWT authentication',
    rationale: 'Stateless scaling requirement',
    context: ['auth.service.ts'],
    timestamp: new Date().toISOString(),
    confidence: 0.9
  }],
  modifications: [],
  modules: [],
  risks: [],
  patterns: [],
  failures: []
};

Stage 2: Summarization (post-session)

import { SessionSummary } from '@codmir/agent-contracts';

const summary: SessionSummary = {
  sessionId: 'sess_123',
  summarizedAt: new Date().toISOString(),
  intent: 'Analyze authentication system',
  outcome: {
    success: true,
    summary: 'Completed analysis, identified 3 risks',
    metrics: {
      filesAnalyzed: 12,
      filesModified: 0,
      artifactsProduced: 2,
      decisionsRecorded: 1,
      tasksCompleted: 3,
      duration: 1800 // seconds
    }
  },
  findings: [],
  affectedScope: { files: [], modules: [], features: [] },
  artifacts: [],
  reusablePatterns: [],
  failedApproaches: [],
  nextActions: []
};

Stage 3: Promotion (background)

import { KnowledgePromotion, PromotionRules } from '@codmir/agent-contracts';

const promotion: KnowledgePromotion = {
  promotionId: 'prom_123',
  domain: 'authentication',
  category: 'fact',
  content: 'JWT tokens expire after 24 hours',
  confidence: 0.95,
  sources: ['sess_123', 'sess_124', 'sess_125'],
  firstSeen: '2026-03-01T00:00:00Z',
  lastVerified: '2026-03-07T23:37:00Z',
  verificationCount: 3,
  tags: ['auth', 'jwt', 'security'],
  metadata: {
    projectId: 'proj_456',
    promotedAt: new Date().toISOString(),
    reviewStatus: 'auto'
  }
};

// Promotion rules
const rules: PromotionRules = {
  minSessionCount: 3,
  minConfidence: 0.80,
  minTimeSpan: 7, // days
  requiresConsistency: true,
  autoPromoteCategories: ['architecture', 'convention', 'rule'],
  reviewRequiredCategories: ['breaking-change', 'security']
};

Artifact Contracts (artifact.ts)

First-class artifact management:

import { Artifact, ArtifactType } from '@codmir/agent-contracts';

const artifact: Artifact = {
  artifactId: 'art_123',
  sessionId: 'sess_123',
  type: 'architecture-map',
  name: 'Authentication Flow Diagram',
  content: '# Architecture...',
  status: 'approved',
  metadata: {
    size: 2048,
    mimeType: 'text/markdown',
    hash: 'sha256:...',
    version: 1
  },
  creator: {
    type: 'agent',
    id: 'agent_1',
    name: 'Analyzer'
  },
  relatedFiles: ['src/auth/auth.service.ts'],
  tags: ['architecture', 'auth'],
  createdAt: new Date().toISOString()
};

Session Events (session-events.ts)

Event-driven session lifecycle:

import { SessionEvent, SessionEventType } from '@codmir/agent-contracts';

const event: SessionEvent = {
  eventId: 'evt_123',
  sessionId: 'sess_123',
  type: 'session.task_completed',
  timestamp: new Date().toISOString(),
  actor: {
    type: 'agent',
    id: 'agent_1',
    name: 'Analyzer'
  },
  data: {
    taskId: 'task_456',
    taskName: 'Analyze auth module',
    result: { success: true }
  }
};

Session Residue Contract (Required Minimum)

Every session must produce this before closing:

import { SessionResidueMinimum } from '@codmir/agent-contracts';

const residue: SessionResidueMinimum = {
  sessionId: 'sess_123',
  projectId: 'proj_456',
  intent: 'Analyze authentication flow',
  outcome: {
    success: true,
    summary: 'Completed analysis',
    metrics: {
      filesAnalyzed: 12,
      artifactsProduced: 2,
      decisionsRecorded: 1
    }
  },
  findings: [
    {
      type: 'risk',
      content: 'Missing rate limiting on login endpoint',
      confidence: 0.85,
      impact: 'high'
    }
  ],
  scope: {
    files: ['src/auth/auth.service.ts', 'src/auth/jwt.service.ts'],
    modules: ['authentication'],
    features: ['login', 'token-management']
  },
  promotions: [
    {
      type: 'convention',
      content: 'Authentication uses JWT with 24h expiry',
      weight: 0.9
    }
  ],
  nextActions: [
    {
      type: 'task',
      description: 'Add rate limiting to login endpoint',
      priority: 8
    }
  ],
  createdAt: '2026-03-07T23:00:00Z',
  completedAt: '2026-03-07T23:30:00Z'
};

// Validate
SessionResidueMinimumSchema.parse(residue);

Storage Metadata

Track artifacts across storage tiers:

import { StorageMetadata, StorageTier } from '@codmir/agent-contracts';

const metadata: StorageMetadata = {
  tier: 'warm',
  location: 's3://codmir-sessions/proj_456/sess_123/summary.json',
  size: 2048,
  compressed: true,
  compressionRatio: 8.5,
  accessCount: 12,
  lastAccessed: '2026-03-07T23:37:00Z',
  retentionPolicy: '90-days'
};

Distillation Jobs

Background processing:

import { DistillationJob } from '@codmir/agent-contracts';

const job: DistillationJob = {
  jobId: 'job_123',
  type: 'promotion',
  status: 'running',
  target: {
    projectId: 'proj_456',
    sessionIds: ['sess_123', 'sess_124', 'sess_125']
  },
  schedule: {
    scheduledAt: '2026-03-08T00:00:00Z',
    startedAt: '2026-03-08T00:00:05Z'
  }
};

Metrics Tracking

Monitor distillation efficiency:

import { DistillationMetrics } from '@codmir/agent-contracts';

const metrics: DistillationMetrics = {
  sessionId: 'sess_123',
  projectId: 'proj_456',
  stage: 'summarization',
  timing: {
    startedAt: '2026-03-07T23:30:00Z',
    completedAt: '2026-03-07T23:30:15Z',
    duration: 15000 // ms
  },
  input: {
    size: 102400, // bytes
    tokenCount: 25000
  },
  output: {
    size: 2048,
    tokenCount: 500
  },
  compression: {
    ratio: 50,
    bytesReduced: 100352
  },
  quality: {
    extractedItems: 5,
    promotedItems: 1,
    confidenceAverage: 0.87
  }
};

Other Existing Contracts

This package also exports:

• Repo Index - File structure, symbols, dependencies
• Context Map - Navigation graph for agent reasoning
• Workflow - Reusable execution procedures
• Knowledge Base - Durable semantic understanding
• Skills - Bounded agent capabilities
• Context Bundle - Selective context assembly
• Model Router - AI model selection logic

See individual module files for full documentation.

Development

# Build contracts
pnpm build

# Watch mode
pnpm dev

Integration Example

import {
  SessionState,
  SessionExtraction,
  SessionSummary,
  KnowledgePromotion,
  Artifact,
  SessionEvent
} from '@codmir/agent-contracts';

// 1. Session starts
const session: SessionState = { /* ... */ };

// 2. During execution - extract structured data
const extraction: SessionExtraction = { /* ... */ };

// 3. On completion - summarize
const summary: SessionSummary = { /* ... */ };

// 4. Background - promote to knowledge
const promotion: KnowledgePromotion = { /* ... */ };

// 5. Track everything via events
const event: SessionEvent = {
  type: 'distillation.summarization_completed',
  // ...
};

License

MIT