cognitive-core 0.0.2 → 0.1.2

package/src/types/config.ts

@@ -0,0 +1,585 @@
+import { z } from 'zod';
+
+/**
+ * Credit assignment strategy for trajectory analysis
+ */
+export const CreditStrategySchema = z.enum(['simple', 'llm', 'counterfactual']);
+export type CreditStrategy = z.infer<typeof CreditStrategySchema>;
+
+/**
+ * Pattern extraction approach
+ */
+export const PatternExtractorSchema = z.enum(['llm', 'text', 'both']);
+export type PatternExtractor = z.infer<typeof PatternExtractorSchema>;
+
+/**
+ * Learning pipeline configuration
+ */
+export const LearningConfigSchema = z.object({
+  /** How to assign credit to steps */
+  creditStrategy: CreditStrategySchema.default('simple'),
+  /** How to extract patterns */
+  patternExtractor: PatternExtractorSchema.default('llm'),
+  /** Minimum trajectories before batch learning */
+  minTrajectories: z.number().default(10),
+  /** Minimum hours since last batch learning */
+  minHoursSinceLast: z.number().optional(),
+  /** Minimum success rate for extraction */
+  minSuccessRate: z.number().min(0).max(1).optional(),
+  /** Similarity threshold for deduplication */
+  deduplicationThreshold: z.number().min(0).max(1).default(0.9),
+  /** Maximum experiences to keep during pruning (default: 1000) */
+  maxExperiences: z.number().default(1000),
+});
+
+export type LearningConfig = z.infer<typeof LearningConfigSchema>;
+
+/**
+ * Task routing configuration
+ */
+export const RouterConfigSchema = z.object({
+  /** Threshold for considering tasks similar */
+  similarityThreshold: z.number().min(0).max(1).default(0.85),
+  /** Enable domain-based routing */
+  useDomainRouting: z.boolean().default(true),
+  /** Default search strategy */
+  defaultStrategy: z.string().default('direct'),
+});
+
+export type RouterConfig = z.infer<typeof RouterConfigSchema>;
+
+/**
+ * Memory capacity limits for automatic pruning
+ */
+export const MemoryCapacityConfigSchema = z.object({
+  /** Maximum number of experiences to store (0 = unlimited) */
+  maxExperiences: z.number().default(0),
+  /** Maximum number of playbooks to store (0 = unlimited) */
+  maxPlaybooks: z.number().default(0),
+  /** Maximum age of experiences in days (0 = unlimited) */
+  maxExperienceAgeDays: z.number().default(0),
+  /** Maximum age of failed experiences in days (shorter than successful) */
+  maxFailedExperienceAgeDays: z.number().default(30),
+  /** Enable automatic pruning when limits are exceeded */
+  autoPrune: z.boolean().default(true),
+  /** Preserve domain coverage when pruning */
+  preserveDomainCoverage: z.boolean().default(true),
+  /** Similarity threshold for deduplication (0 = disabled) */
+  deduplicationThreshold: z.number().min(0).max(1).default(0),
+});
+
+export type MemoryCapacityConfig = z.infer<typeof MemoryCapacityConfigSchema>;
+
+/**
+ * Memory retrieval configuration
+ */
+export const MemoryConfigSchema = z.object({
+  /** Maximum experiences to retrieve */
+  maxExperiences: z.number().default(4), // ReMem paper default
+  /** Maximum strategies to retrieve */
+  maxStrategies: z.number().default(3),
+  /** Maximum concepts to retrieve */
+  maxConcepts: z.number().default(5),
+  /** Maximum skills to retrieve */
+  maxSkills: z.number().default(3),
+  /** Maximum tokens for memory context */
+  maxContextTokens: z.number().default(4000),
+  /** Capacity limits for storage */
+  capacity: MemoryCapacityConfigSchema.default({}),
+});
+
+export type MemoryConfig = z.infer<typeof MemoryConfigSchema>;
+
+/**
+ * Storage configuration
+ */
+export const StorageConfigSchema = z.object({
+  /** Base directory for file storage */
+  baseDir: z.string().default('.atlas'),
+  /** Enable file-based persistence */
+  persistenceEnabled: z.boolean().default(true),
+  /** Auto-save interval in milliseconds */
+  autoSaveInterval: z.number().default(60000), // 1 minute
+});
+
+export type StorageConfig = z.infer<typeof StorageConfigSchema>;
+
+/**
+ * Embedding provider type
+ */
+export const EmbeddingProviderTypeSchema = z.enum([
+  'openai',
+  'voyage',
+  'local',
+  'none',
+]);
+export type EmbeddingProviderType = z.infer<typeof EmbeddingProviderTypeSchema>;
+
+/**
+ * Embedding configuration
+ */
+export const EmbeddingConfigSchema = z.object({
+  /** Embedding provider type */
+  provider: EmbeddingProviderTypeSchema.default('none'),
+  /** API key for hosted providers (OpenAI, Voyage) */
+  apiKey: z.string().optional(),
+  /** Model name/identifier */
+  model: z.string().optional(),
+  /** Path to local model (for 'local' provider) */
+  modelPath: z.string().optional(),
+  /** Embedding dimension (defaults vary by provider) */
+  dimension: z.number().optional(),
+  /** Path for sqlite-vec database file */
+  vectorDbPath: z.string().default('.atlas/vectors.db'),
+  /** Base URL for API (for custom endpoints) */
+  baseUrl: z.string().optional(),
+});
+
+export type EmbeddingConfig = z.infer<typeof EmbeddingConfigSchema>;
+
+/**
+ * Execution backend type
+ */
+export const ExecutionBackendSchema = z.enum(['acp', 'subprocess', 'mock']);
+export type ExecutionBackend = z.infer<typeof ExecutionBackendSchema>;
+
+/**
+ * Execution configuration
+ */
+export const ExecutionConfigSchema = z.object({
+  /** Backend to use for agent execution */
+  backend: ExecutionBackendSchema.default('acp'),
+  /** Maximum execution time in seconds */
+  maxExecutionTime: z.number().default(300),
+  /** Capture tool calls for trajectory extraction */
+  captureToolCalls: z.boolean().default(true),
+  /** Default agent type */
+  defaultAgentType: z.string().default('claude-code'),
+});
+
+export type ExecutionConfig = z.infer<typeof ExecutionConfigSchema>;
+
+/**
+ * Compute provider configuration
+ */
+export const ComputeProviderConfigSchema = z.object({
+  /** Default cost tier preference */
+  defaultCostTier: z.enum(['free', 'low', 'medium', 'high']).default('low'),
+  /** Default location preference */
+  defaultLocation: z.enum(['local', 'remote', 'any']).default('local'),
+  /** Fallback to any available source if preferred not available */
+  allowFallback: z.boolean().default(true),
+});
+
+export type ComputeProviderConfig = z.infer<typeof ComputeProviderConfigSchema>;
+
+/**
+ * Refinement configuration
+ */
+export const RefinementConfigSchema = z.object({
+  /** Maximum refinement iterations */
+  maxIterations: z.number().min(1).max(10).default(3),
+  /** Minimum quality score to accept without refinement */
+  acceptableScore: z.number().min(0).max(1).default(0.7),
+  /** Whether to use ACP agent for evaluation */
+  useAgentEvaluation: z.boolean().default(true),
+  /** Agent type to use for evaluation */
+  evaluatorAgentType: z.string().default('evaluator'),
+  /** Confidence threshold below which to trigger refinement */
+  confidenceThreshold: z.number().min(0).max(1).default(0.6),
+  /** Routing strategies that should trigger refinement */
+  triggerOnStrategies: z
+    .array(z.enum(['explore', 'fallback', 'direct', 'adapt']))
+    .default(['explore', 'fallback']),
+});
+
+export type RefinementConfig = z.infer<typeof RefinementConfigSchema>;
+
+/**
+ * Skill Library promotion criteria
+ */
+export const SkillPromotionConfigSchema = z.object({
+  /** Minimum confidence to promote to core skill */
+  minConfidence: z.number().min(0).max(1).default(0.85),
+  /** Minimum success count to promote */
+  minSuccessCount: z.number().default(5),
+  /** Minimum success rate to promote */
+  minSuccessRate: z.number().min(0).max(1).default(0.8),
+});
+
+export type SkillPromotionConfig = z.infer<typeof SkillPromotionConfigSchema>;
+
+/**
+ * Skill Library capacity limits
+ */
+export const SkillLimitsConfigSchema = z.object({
+  /** Maximum core skills (always in system prompt) */
+  maxCoreSkills: z.number().default(10),
+  /** Maximum domain skills per domain */
+  maxDomainSkills: z.number().default(5),
+  /** Maximum contextual playbooks per task */
+  maxContextualPlaybooks: z.number().default(3),
+});
+
+export type SkillLimitsConfig = z.infer<typeof SkillLimitsConfigSchema>;
+
+/**
+ * Skill Library context budget
+ */
+export const SkillContextConfigSchema = z.object({
+  /** Maximum tokens for skills in system prompt */
+  maxTokensForSkills: z.number().default(2000),
+  /** Include refinements in skill context */
+  includeRefinements: z.boolean().default(true),
+  /** Include code examples in skill context */
+  includeExamples: z.boolean().default(false),
+  /** Cache refresh interval in milliseconds (default: 5 minutes) */
+  cacheRefreshInterval: z.number().default(5 * 60 * 1000),
+});
+
+export type SkillContextConfig = z.infer<typeof SkillContextConfigSchema>;
+
+/**
+ * Skill Library demotion criteria
+ */
+export const SkillDemotionConfigSchema = z.object({
+  /** Number of consecutive failures before demotion */
+  failureThreshold: z.number().default(3),
+  /** Minimum confidence to retain core skill status */
+  minConfidenceToRetain: z.number().min(0).max(1).default(0.6),
+});
+
+export type SkillDemotionConfig = z.infer<typeof SkillDemotionConfigSchema>;
+
+/**
+ * Skill Library configuration - all thresholds configurable
+ */
+export const SkillLibraryConfigSchema = z.object({
+  /** Promotion criteria */
+  promotion: SkillPromotionConfigSchema.default({}),
+  /** Capacity limits */
+  limits: SkillLimitsConfigSchema.default({}),
+  /** Context budget */
+  context: SkillContextConfigSchema.default({}),
+  /** Demotion criteria */
+  demotion: SkillDemotionConfigSchema.default({}),
+});
+
+export type SkillLibraryConfig = z.infer<typeof SkillLibraryConfigSchema>;
+
+/**
+ * Agentic Task Runner configuration
+ */
+export const AgenticTaskRunnerConfigSchema = z.object({
+  /** Cleanup workspaces after completion */
+  cleanupWorkspaces: z.boolean().default(true),
+  /** Keep workspaces for failed tasks (for debugging) */
+  keepFailedWorkspaces: z.boolean().default(true),
+  /** Maximum concurrent analysis agents */
+  maxConcurrentAgents: z.number().default(3),
+  /** Stale workspace cleanup threshold in milliseconds */
+  staleWorkspaceMaxAgeMs: z.number().default(3600_000),
+  /** Base directory for workspaces (defaults to os.tmpdir()) */
+  workspaceBaseDir: z.string().optional(),
+});
+
+export type AgenticTaskRunnerConfig = z.infer<typeof AgenticTaskRunnerConfigSchema>;
+
+/**
+ * MCP Server configuration
+ */
+export const MCPServerConfigSchema = z.object({
+  /** Enable MCP server */
+  enabled: z.boolean().default(false),
+  /** Port for standalone server */
+  port: z.number().optional(),
+  /** Expose playbooks as MCP resources */
+  exposeResources: z.boolean().default(true),
+  /** Expose playbook tools */
+  exposeTools: z.boolean().default(true),
+  /** Maximum results to return from searches */
+  maxResults: z.number().default(5),
+  /** Minimum confidence threshold for search results */
+  minConfidence: z.number().min(0).max(1).default(0.3),
+  /** Include refinements in playbook details */
+  includeRefinements: z.boolean().default(true),
+  /** Enable filtering by domain */
+  enableDomainFiltering: z.boolean().default(true),
+});
+
+export type MCPServerConfig = z.infer<typeof MCPServerConfigSchema>;
+
+/**
+ * Compression configuration for team trajectory ingestion
+ */
+export const CompressionConfigSchema = z.object({
+  /** Maximum tokens per agent after compression */
+  maxTokensPerAgent: z.number().default(5000),
+  /** Preserve interaction boundary steps at full fidelity */
+  preserveInteractionBoundaries: z.boolean().default(true),
+  /** Minimum consecutive non-key steps before folding */
+  foldThreshold: z.number().default(5),
+  /** Maximum ratio of steps to mark as critical */
+  maxCriticalRatio: z.number().default(0.25),
+  /** Score threshold for critical steps */
+  criticalStepThreshold: z.number().default(0.3),
+  /** Score threshold for critical interactions */
+  criticalInteractionThreshold: z.number().default(0.3),
+});
+
+export type CompressionConfig = z.infer<typeof CompressionConfigSchema>;
+
+/**
+ * Team-aware learning configuration
+ */
+export const TeamLearningConfigSchema = z.object({
+  /** Enable team-aware learning */
+  enabled: z.boolean().default(false),
+  /** Minimum team trajectories before batch learning */
+  minTeamTrajectories: z.number().default(5),
+  /** Similarity threshold for team playbook deduplication */
+  deduplicationThreshold: z.number().min(0).max(1).default(0.85),
+  /** Weight of structural metrics in analysis (0 = ignore, 1 = metrics only) */
+  metricsWeight: z.number().min(0).max(1).default(0.3),
+  /** Maximum team experiences to store */
+  maxTeamExperiences: z.number().default(200),
+  /** Maximum team playbooks to store */
+  maxTeamPlaybooks: z.number().default(50),
+  /** Maximum role playbooks to store */
+  maxRolePlaybooks: z.number().default(100),
+  /** Analysis agent timeout in milliseconds */
+  analysisTimeout: z.number().default(300_000),
+  /** Extraction agent timeout in milliseconds */
+  extractionTimeout: z.number().default(600_000),
+  /** Compression settings for trajectory ingestion */
+  compression: CompressionConfigSchema.default({}),
+});
+
+export type TeamLearningConfig = z.infer<typeof TeamLearningConfigSchema>;
+
+/**
+ * Knowledge Bank confidence model configuration
+ */
+export const ConfidenceConfigSchema = z.object({
+  /** Initial confidence for extracted observations */
+  extractedInitial: z.number().min(0).max(1).default(0.3),
+  /** Initial confidence for agent-authored notes */
+  agentAuthoredInitial: z.number().min(0).max(1).default(0.5),
+  /** EMA alpha for reinforcement */
+  reinforcementAlpha: z.number().min(0).max(1).default(0.1),
+  /** Confidence reduction on contradiction */
+  contradictionPenalty: z.number().min(0).max(1).default(0.3),
+  /** Daily confidence decay rate for unvalidated knowledge */
+  dailyDecayRate: z.number().min(0).max(0.1).default(0.001),
+  /** Confidence below which to mark as stale */
+  staleThreshold: z.number().min(0).max(1).default(0.2),
+  /** Days without validation before decay begins */
+  decayGracePeriodDays: z.number().default(90),
+});
+
+export type ConfidenceConfig = z.infer<typeof ConfidenceConfigSchema>;
+
+/**
+ * Knowledge Bank graph overlay configuration
+ */
+export const GraphConfigSchema = z.object({
+  /** Which graph layers to enable */
+  enabledLayers: z
+    .array(z.enum(['semantic', 'temporal', 'causal', 'entity']))
+    .default(['semantic']),
+  /** Whether to auto-infer temporal edges from timestamps */
+  inferTemporalEdges: z.boolean().default(true),
+  /** Whether to auto-infer causal edges from failure-recovery patterns */
+  inferCausalEdges: z.boolean().default(true),
+  /** Whether to auto-infer entity edges from shared entity tags */
+  inferEntityEdges: z.boolean().default(true),
+  /** Split layer files by domain when node count exceeds this */
+  domainSplitThreshold: z.number().default(500),
+  /** Promote to SQLite when total edge count exceeds this */
+  sqlitePromotionThreshold: z.number().default(10000),
+});
+
+export type GraphConfigType = z.infer<typeof GraphConfigSchema>;
+
+/**
+ * Knowledge Bank defragmentation configuration
+ */
+export const DefragConfigSchema = z.object({
+  /** Minimum inbox items before triggering defrag */
+  minInboxItems: z.number().default(5),
+  /** Whether to auto-consolidate observations into entities */
+  autoConsolidate: z.boolean().default(true),
+  /** Minimum observations about an entity before consolidation */
+  consolidationThreshold: z.number().default(3),
+  /** Whether to auto-regenerate domain summaries */
+  autoRegenerateSummaries: z.boolean().default(true),
+  /** Use LLM for summary generation (vs heuristic concatenation) */
+  llmSummaryGeneration: z.boolean().default(false),
+  /** Whether to auto-resolve simple contradictions */
+  autoResolveContradictions: z.boolean().default(false),
+});
+
+export type DefragConfig = z.infer<typeof DefragConfigSchema>;
+
+/**
+ * Knowledge Bank extraction configuration
+ */
+export const KnowledgeExtractionConfigSchema = z.object({
+  /** Enable automatic knowledge extraction from trajectories */
+  enabled: z.boolean().default(true),
+  /** Use LLM-assisted extraction (vs heuristic only) */
+  useLlmExtraction: z.boolean().default(false),
+  /** Minimum trajectory attribution score for extraction */
+  minAttributionScore: z.number().min(0).max(1).default(0.3),
+});
+
+export type KnowledgeExtractionConfig = z.infer<typeof KnowledgeExtractionConfigSchema>;
+
+/**
+ * Knowledge Bank surfacing configuration
+ */
+export const KnowledgeSurfacingConfigSchema = z.object({
+  /** Include domain summaries in task context */
+  includeDomainSummaries: z.boolean().default(true),
+  /** Include entity notes in task context */
+  includeEntityNotes: z.boolean().default(true),
+  /** Maximum knowledge notes to surface per task */
+  maxNotesPerTask: z.number().default(5),
+  /** Maximum tokens for knowledge context */
+  maxTokensForKnowledge: z.number().default(1500),
+  /** Include evidence citations in surfaced notes */
+  includeEvidence: z.boolean().default(false),
+  /** Include graph links in surfaced notes */
+  includeLinks: z.boolean().default(false),
+});
+
+export type KnowledgeSurfacingConfig = z.infer<typeof KnowledgeSurfacingConfigSchema>;
+
+/**
+ * Knowledge Bank configuration
+ */
+export const KnowledgeBankConfigSchema = z.object({
+  /** Enable knowledge bank */
+  enabled: z.boolean().default(true),
+  /** Root directory for knowledge files (relative to storage.baseDir) */
+  memoryDir: z.string().default('memory'),
+  /** Extraction config */
+  extraction: KnowledgeExtractionConfigSchema.default({}),
+  /** Defragmentation config */
+  defrag: DefragConfigSchema.default({}),
+  /** Confidence model config */
+  confidence: ConfidenceConfigSchema.default({}),
+  /** Graph overlay config */
+  graph: GraphConfigSchema.default({}),
+  /** Surfacing config (independent from SkillLibrary) */
+  surfacing: KnowledgeSurfacingConfigSchema.default({}),
+  /** Whether to manage minimem-specific features (sync, versioning) */
+  minimemAware: z.boolean().default(true),
+});
+
+export type KnowledgeBankConfig = z.infer<typeof KnowledgeBankConfigSchema>;
+
+/**
+ * Session Bank configuration (Entire CLI integration)
+ */
+export const SessionBankConfigSchema = z.object({
+  /** Enable session bank integration */
+  enabled: z.boolean().default(false),
+  /** Orphan branch name */
+  branch: z.string().default('entire/checkpoints/v1'),
+  /** State directory (relative to storage.baseDir) */
+  stateDir: z.string().default('session-bank'),
+  /** Default outcome strategy for synthesis */
+  outcomeStrategy: z.enum(['summary', 'heuristic']).default('summary'),
+  /** Auto-ingest unprocessed sessions on init */
+  autoIngest: z.boolean().default(false),
+  /** Maximum sessions per auto-ingest batch */
+  maxIngestBatch: z.number().default(20),
+});
+
+export type SessionBankConfig = z.infer<typeof SessionBankConfigSchema>;
+
+/**
+ * Skill-tree storage configuration
+ */
+export const SkillTreeConfigSchema = z.object({
+  /** Enable automatic skill-tree publishing via SqliteStorageAdapter */
+  enabled: z.boolean().default(true),
+  /** Path to the SQLite database for skill storage (relative to storage.baseDir) */
+  dbPath: z.string().default('skills.db'),
+});
+
+export type SkillTreeConfig = z.infer<typeof SkillTreeConfigSchema>;
+
+/**
+ * Main Atlas configuration
+ */
+export const AtlasConfigSchema = z.object({
+  /** Learning configuration */
+  learning: LearningConfigSchema.default({}),
+  /** Router configuration */
+  router: RouterConfigSchema.default({}),
+  /** Memory configuration */
+  memory: MemoryConfigSchema.default({}),
+  /** Storage configuration */
+  storage: StorageConfigSchema.default({}),
+  /** Embedding configuration */
+  embedding: EmbeddingConfigSchema.default({}),
+  /** Execution configuration */
+  execution: ExecutionConfigSchema.default({}),
+  /** Refinement configuration */
+  refinement: RefinementConfigSchema.default({}),
+  /** Skill Library configuration */
+  skillLibrary: SkillLibraryConfigSchema.default({}),
+  /** MCP Server configuration */
+  mcp: MCPServerConfigSchema.default({}),
+  /** Agentic Task Runner configuration */
+  agenticTasks: AgenticTaskRunnerConfigSchema.default({}),
+  /** Compute provider configuration */
+  compute: ComputeProviderConfigSchema.default({}),
+  /** Team-aware learning configuration */
+  teamLearning: TeamLearningConfigSchema.default({}),
+  /** Knowledge bank configuration */
+  knowledgeBank: KnowledgeBankConfigSchema.default({}),
+  /** Skill-tree storage configuration */
+  skillTree: SkillTreeConfigSchema.default({}),
+  /** Session bank configuration (Entire CLI integration) */
+  sessionBank: SessionBankConfigSchema.default({}),
+});
+
+export type AtlasConfig = z.infer<typeof AtlasConfigSchema>;
+
+/**
+ * Create default configuration
+ */
+export function createDefaultConfig(
+  overrides?: Partial<AtlasConfig>
+): AtlasConfig {
+  return AtlasConfigSchema.parse(overrides ?? {});
+}
+
+/**
+ * Merge configurations
+ */
+export function mergeConfig(
+  base: AtlasConfig,
+  overrides: Partial<AtlasConfig>
+): AtlasConfig {
+  return AtlasConfigSchema.parse({
+    learning: { ...base.learning, ...overrides.learning },
+    router: { ...base.router, ...overrides.router },
+    memory: { ...base.memory, ...overrides.memory },
+    storage: { ...base.storage, ...overrides.storage },
+    embedding: { ...base.embedding, ...overrides.embedding },
+    execution: { ...base.execution, ...overrides.execution },
+    refinement: { ...base.refinement, ...overrides.refinement },
+    skillLibrary: { ...base.skillLibrary, ...overrides.skillLibrary },
+    mcp: { ...base.mcp, ...overrides.mcp },
+    agenticTasks: { ...base.agenticTasks, ...overrides.agenticTasks },
+    compute: { ...base.compute, ...overrides.compute },
+    teamLearning: { ...base.teamLearning, ...overrides.teamLearning },
+    knowledgeBank: { ...base.knowledgeBank, ...overrides.knowledgeBank },
+    skillTree: { ...base.skillTree, ...overrides.skillTree },
+    sessionBank: { ...base.sessionBank, ...overrides.sessionBank },
+  });
+}

package/src/types/dataclaw.ts

@@ -0,0 +1,99 @@
+import { z } from 'zod';
+
+// ============================================================================
+// DataClaw — types for the dataclaw JSONL trajectory export format
+// https://github.com/peteromallet/dataclaw
+//
+// DataClaw exports conversation histories from AI coding assistants
+// (Claude Code, Codex, Gemini CLI, OpenCode, etc.) into structured JSONL
+// datasets. Each line is one complete coding session.
+// ============================================================================
+
+/**
+ * A tool invocation within a dataclaw assistant message.
+ */
+export const DataclawToolUseSchema = z.object({
+  /** Tool name (e.g. "bash", "Read", "Write", "Grep", "exec_command") */
+  tool: z.string(),
+  /** Structured arguments passed to the tool */
+  input: z.record(z.unknown()).default({}),
+  /** Execution result — shape varies by source */
+  output: z.record(z.unknown()).default({}),
+  /** "success" or "error" */
+  status: z.string().default('success'),
+});
+
+export type DataclawToolUse = z.infer<typeof DataclawToolUseSchema>;
+
+/**
+ * A single conversation turn in a dataclaw session.
+ */
+export const DataclawMessageSchema = z.object({
+  /** "user" or "assistant" */
+  role: z.enum(['user', 'assistant']),
+  /** The text content of the message */
+  content: z.string().default(''),
+  /** Extended reasoning / chain-of-thought (optional, Claude-specific) */
+  thinking: z.string().nullable().optional(),
+  /** Tool invocations on assistant messages */
+  tool_uses: z.array(DataclawToolUseSchema).optional(),
+  /** ISO 8601 timestamp */
+  timestamp: z.string().nullable().optional(),
+});
+
+export type DataclawMessage = z.infer<typeof DataclawMessageSchema>;
+
+/**
+ * Aggregate statistics for a dataclaw session.
+ */
+export const DataclawStatsSchema = z.object({
+  user_messages: z.number().default(0),
+  assistant_messages: z.number().default(0),
+  tool_uses: z.number().default(0),
+  input_tokens: z.number().default(0),
+  output_tokens: z.number().default(0),
+});
+
+export type DataclawStats = z.infer<typeof DataclawStatsSchema>;
+
+/**
+ * A complete coding session — one line of the dataclaw JSONL export.
+ */
+export const DataclawSessionSchema = z.object({
+  /** Unique session identifier */
+  session_id: z.string(),
+  /** Project/directory name (anonymized) */
+  project: z.string().default(''),
+  /** AI model used (e.g. "claude-opus-4-6") */
+  model: z.string().default(''),
+  /** Source tool ("claude", "codex", "gemini", "opencode", "openclaw", "kimi", "custom") */
+  source: z.string().default(''),
+  /** Git branch active during the session */
+  git_branch: z.string().nullable().optional(),
+  /** ISO 8601 start time */
+  start_time: z.string().nullable().optional(),
+  /** ISO 8601 end time */
+  end_time: z.string().nullable().optional(),
+  /** Ordered conversation turns */
+  messages: z.array(DataclawMessageSchema).default([]),
+  /** Aggregate session stats */
+  stats: DataclawStatsSchema.optional(),
+});
+
+export type DataclawSession = z.infer<typeof DataclawSessionSchema>;
+
+/**
+ * Export-level metadata (metadata.json companion file).
+ */
+export const DataclawMetadataSchema = z.object({
+  sessions: z.number().default(0),
+  skipped: z.number().default(0),
+  redactions: z.number().default(0),
+  models: z.record(z.number()).default({}),
+  projects: z.array(z.string()).default([]),
+  total_input_tokens: z.number().default(0),
+  total_output_tokens: z.number().default(0),
+  exported_at: z.string().optional(),
+});
+
+export type DataclawMetadata = z.infer<typeof DataclawMetadataSchema>;

package/src/types/huggingface-transformers.d.ts

@@ -0,0 +1,12 @@
+// Type declaration for optional @huggingface/transformers dependency
+declare module "@huggingface/transformers" {
+  export function pipeline(
+    task: string,
+    model: string,
+    options?: Record<string, unknown>,
+  ): Promise<(input: string, options?: Record<string, unknown>) => Promise<{ data: Float32Array }>>;
+
+  export const env: {
+    cacheDir?: string;
+  };
+}