@dot-ai/core 0.5.2 → 0.8.0

package/src/format.test.ts

@@ -0,0 +1,218 @@
+import { describe, it, expect, vi } from 'vitest';
+import { formatContext } from './format.js';
+import type { EnrichedContext, BudgetWarning, Skill, MemoryEntry, Identity } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeContext(overrides?: Partial<EnrichedContext>): EnrichedContext {
+  return {
+    prompt: 'test prompt',
+    labels: [],
+    identities: [],
+    memories: [],
+    skills: [],
+    tools: [],
+    routing: { model: 'default', reason: 'test' },
+    ...overrides,
+  };
+}
+
+function makeSkill(name: string, contentLength: number): Skill {
+  return {
+    name,
+    description: `Skill ${name}`,
+    labels: [],
+    content: 'x'.repeat(contentLength),
+  };
+}
+
+function makeMemory(content: string): MemoryEntry {
+  return {
+    content,
+    type: 'fact',
+    source: 'test',
+  };
+}
+
+function makeIdentity(content: string, priority = 10): Identity {
+  return {
+    type: 'agents',
+    content,
+    source: 'test',
+    priority,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('formatContext budget', () => {
+  it('no budget — returns full content', () => {
+    const ctx = makeContext({
+      skills: [
+        makeSkill('skill-a', 100),
+        makeSkill('skill-b', 100),
+        makeSkill('skill-c', 100),
+      ],
+    });
+
+    const result = formatContext(ctx);
+
+    expect(result).toContain('skill-a');
+    expect(result).toContain('skill-b');
+    expect(result).toContain('skill-c');
+  });
+
+  it('under budget — no trimming', () => {
+    const ctx = makeContext({
+      skills: [makeSkill('small-skill', 50)],
+    });
+
+    const onBudgetExceeded = vi.fn();
+    const result = formatContext(ctx, { tokenBudget: 10000, onBudgetExceeded });
+
+    expect(result).toContain('small-skill');
+    expect(onBudgetExceeded).not.toHaveBeenCalled();
+  });
+
+  it('over budget — drops skills by reverse order', () => {
+    // 5 skills × 1000 chars = ~5000 chars = ~1250 tokens for skills alone
+    const ctx = makeContext({
+      skills: [
+        makeSkill('skill-1', 1000),
+        makeSkill('skill-2', 1000),
+        makeSkill('skill-3', 1000),
+        makeSkill('skill-4', 1000),
+        makeSkill('skill-5', 1000),
+      ],
+    });
+
+    const actions: string[] = [];
+    const onBudgetExceeded = vi.fn((w: BudgetWarning) => actions.push(...w.actions));
+
+    formatContext(ctx, { tokenBudget: 500, onBudgetExceeded });
+
+    expect(onBudgetExceeded).toHaveBeenCalled();
+    const droppedActions = actions.filter(a => a.startsWith('dropped skill:'));
+    expect(droppedActions.length).toBeGreaterThan(0);
+  });
+
+  it('over budget — truncates skills first before dropping', () => {
+    // 2 skills × 5000 chars = ~10000 chars = ~2500 tokens
+    // New order: strategy 1 (truncate to 2000) fires FIRST
+    // After truncation: ~4100 chars = ~1025 tokens — still over 800
+    // Strategy 3 then drops big-skill-b to bring it under budget
+    const ctx = makeContext({
+      skills: [
+        makeSkill('big-skill-a', 5000),
+        makeSkill('big-skill-b', 5000),
+      ],
+    });
+
+    const actions: string[] = [];
+    const onBudgetExceeded = vi.fn((w: BudgetWarning) => actions.push(...w.actions));
+
+    formatContext(ctx, { tokenBudget: 800, onBudgetExceeded });
+
+    expect(onBudgetExceeded).toHaveBeenCalled();
+    // Truncation must appear before any drop action
+    const truncateIdx = actions.findIndex(a => a.includes('truncated'));
+    const dropIdx = actions.findIndex(a => a.startsWith('dropped skill:'));
+    expect(truncateIdx).toBeGreaterThanOrEqual(0);
+    // If a drop also happened, truncation came first
+    if (dropIdx !== -1) {
+      expect(truncateIdx).toBeLessThan(dropIdx);
+    }
+  });
+
+  it('over budget — drops memories after skills trimmed', () => {
+    // 1 tiny skill + 10 memories × 200 chars = ~2000 chars = ~500 tokens
+    // Budget low enough to trigger memory trimming after skills are already minimal
+    const memories = Array.from({ length: 10 }, (_, i) =>
+      makeMemory('m'.repeat(200) + ` entry-${i}`),
+    );
+
+    const ctx = makeContext({
+      skills: [makeSkill('tiny', 10)],
+      memories,
+    });
+
+    const actions: string[] = [];
+    const onBudgetExceeded = vi.fn((w: BudgetWarning) => actions.push(...w.actions));
+
+    // ~500 token budget: memories alone exceed this, and there's only 1 skill
+    // (can't drop it, strategy 1 requires > 1 skill), truncation won't help much
+    // strategy 3 (drop old memories) should fire
+    formatContext(ctx, { tokenBudget: 100, onBudgetExceeded });
+
+    expect(onBudgetExceeded).toHaveBeenCalled();
+    const memoryActions = actions.filter(a => a.includes('memories'));
+    expect(memoryActions.length).toBeGreaterThan(0);
+    expect(memoryActions[0]).toMatch(/dropped \d+ oldest memories/);
+  });
+
+  it('onBudgetExceeded callback receives correct BudgetWarning', () => {
+    const ctx = makeContext({
+      skills: [
+        makeSkill('alpha', 2000),
+        makeSkill('beta', 2000),
+        makeSkill('gamma', 2000),
+      ],
+    });
+
+    let capturedWarning: BudgetWarning | undefined;
+    const onBudgetExceeded = vi.fn((w: BudgetWarning) => {
+      capturedWarning = w;
+    });
+
+    formatContext(ctx, { tokenBudget: 200, onBudgetExceeded });
+
+    expect(onBudgetExceeded).toHaveBeenCalledOnce();
+    expect(capturedWarning).toBeDefined();
+    expect(capturedWarning!.budget).toBe(200);
+    expect(typeof capturedWarning!.actual).toBe('number');
+    expect(Array.isArray(capturedWarning!.actions)).toBe(true);
+    expect(capturedWarning!.actions.length).toBeGreaterThan(0);
+  });
+
+  it('budget trimming preserves identity sections', () => {
+    const ctx = makeContext({
+      identities: [makeIdentity('You are Kiwi. This is your identity.')],
+      skills: [
+        makeSkill('skill-x', 3000),
+        makeSkill('skill-y', 3000),
+      ],
+    });
+
+    const onBudgetExceeded = vi.fn();
+    // Very low budget — forces trimming, but identities must survive
+    const result = formatContext(ctx, { tokenBudget: 100, onBudgetExceeded });
+
+    expect(result).toContain('You are Kiwi. This is your identity.');
+  });
+
+  it('identity-only overflow calls onBudgetExceeded with non-trimmable message', () => {
+    // Identity content alone exceeds budget — no skills or memories to trim
+    const bigIdentity = 'You are Kiwi. '.repeat(500); // ~7000 chars = ~1750 tokens
+    const ctx = makeContext({
+      identities: [makeIdentity(bigIdentity)],
+      skills: [],
+      memories: [],
+    });
+
+    let capturedWarning: BudgetWarning | undefined;
+    const onBudgetExceeded = vi.fn((w: BudgetWarning) => {
+      capturedWarning = w;
+    });
+
+    formatContext(ctx, { tokenBudget: 100, onBudgetExceeded });
+
+    expect(onBudgetExceeded).toHaveBeenCalledOnce();
+    expect(capturedWarning).toBeDefined();
+    expect(capturedWarning!.actions).toHaveLength(1);
+    expect(capturedWarning!.actions[0]).toContain('non-trimmable');
+  });
+});

package/src/format.ts

@@ -1,5 +1,6 @@
-import type { EnrichedContext, MemoryEntry, Skill, Tool, RoutingResult } from './types.js';
+import type { EnrichedContext, MemoryEntry, Skill, Task, Tool, RoutingResult, BudgetWarning } from './types.js';
 import type { Logger } from './logger.js';
+import type { Capability } from './capabilities.js';
 
 export interface FormatOptions {
   /** Skip identity sections (useful when already injected at session start) */
@@ -8,8 +9,14 @@ export interface FormatOptions {
   maxSkillLength?: number;
   /** Max number of skills to include (already sorted by match relevance). Default: unlimited */
   maxSkills?: number;
+  /** Max estimated tokens (chars / 4). When exceeded, content is trimmed. Default: no limit */
+  tokenBudget?: number;
+  /** Called when budget was exceeded and trimming occurred. Diagnostic signal. */
+  onBudgetExceeded?: (warning: BudgetWarning) => void;
   /** Optional logger for tracing */
   logger?: Logger;
+  /** Skill disclosure mode. 'progressive' shows name+description only, 'full' shows entire content */
+  skillDisclosure?: 'full' | 'progressive';
 }
 
 /**
@@ -20,9 +27,12 @@ export function formatContext(ctx: EnrichedContext, options?: FormatOptions): st
   const start = performance.now();
   const sections: string[] = [];
 
-  // Identity sections (sorted by priority, highest first)
+  // Identity sections (sorted by priority DESC, then by type alphabetically for stability)
   if (!options?.skipIdentities) {
-    const sortedIdentities = [...ctx.identities].sort((a, b) => b.priority - a.priority);
+    const sortedIdentities = [...ctx.identities].sort((a, b) => {
+      if (b.priority !== a.priority) return b.priority - a.priority;
+      return a.type.localeCompare(b.type);
+    });
     for (const identity of sortedIdentities) {
       if (identity.content) {
         sections.push(identity.content);
@@ -30,23 +40,35 @@ export function formatContext(ctx: EnrichedContext, options?: FormatOptions): st
     }
   }
 
-  // Memory section
-  if (ctx.memories.length > 0) {
-    sections.push(formatMemory(ctx.memories));
+  // Memory section (sorted by date DESC for stability)
+  const sortedMemories = [...ctx.memories].sort((a, b) => {
+    if (!a.date && !b.date) return 0;
+    if (!a.date) return 1;
+    if (!b.date) return -1;
+    return b.date.localeCompare(a.date);
+  });
+  if (sortedMemories.length > 0 || ctx.memoryDescription) {
+    sections.push(formatMemory(sortedMemories, ctx.memoryDescription));
+  }
+
+  // Recent tasks section
+  if (ctx.recentTasks && ctx.recentTasks.length > 0) {
+    sections.push(formatTasks(ctx.recentTasks));
   }
 
-  // Skills section
-  let loadedSkills = ctx.skills.filter(s => s.content);
+  // Skills section (sorted by name alphabetically for determinism)
+  let loadedSkills = [...ctx.skills].sort((a, b) => a.name.localeCompare(b.name)).filter(s => s.content);
   if (options?.maxSkills != null) {
     loadedSkills = loadedSkills.slice(0, options.maxSkills);
   }
   if (loadedSkills.length > 0) {
-    sections.push(formatSkills(loadedSkills, options?.maxSkillLength));
+    sections.push(formatSkills(loadedSkills, options?.maxSkillLength, options?.skillDisclosure));
   }
 
-  // Tools section
-  if (ctx.tools.length > 0) {
-    sections.push(formatTools(ctx.tools));
+  // Tools section (sorted by name alphabetically for determinism)
+  const sortedTools = [...ctx.tools].sort((a, b) => a.name.localeCompare(b.name));
+  if (sortedTools.length > 0) {
+    sections.push(formatTools(sortedTools));
   }
 
   // Routing hint
@@ -54,6 +76,75 @@ export function formatContext(ctx: EnrichedContext, options?: FormatOptions): st
     sections.push(formatRouting(ctx.routing));
   }
 
+  // Budget enforcement — trim if over token budget
+  if (options?.tokenBudget != null) {
+    const estimate = () => Math.round(sections.join('\n\n---\n\n').length / 4);
+    let current = estimate();
+
+    if (current > options.tokenBudget) {
+      const actions: string[] = [];
+      const skillSectionIdx = sections.findIndex(s => s.startsWith('## Active Skills'));
+      const memorySectionIdx = sections.findIndex(s => s.startsWith('## Relevant Memory'));
+
+      // Strategy 1: Truncate skill content to 2000 chars
+      if (current > options.tokenBudget && skillSectionIdx !== -1 && options?.maxSkillLength == null) {
+        const longSkills = loadedSkills.filter(s => (s.content?.length ?? 0) > 2000).length;
+        if (longSkills > 0) {
+          sections[skillSectionIdx] = formatSkills(loadedSkills, 2000, options?.skillDisclosure);
+          actions.push(`truncated ${longSkills} skills to 2000 chars`);
+          current = estimate();
+        }
+      }
+
+      // Strategy 2: Drop oldest memories (keep most recent 5)
+      if (current > options.tokenBudget && memorySectionIdx !== -1 && sortedMemories.length > 5) {
+        const kept = sortedMemories.slice(0, 5);
+        const dropped = sortedMemories.length - 5;
+        sections[memorySectionIdx] = formatMemory(kept, ctx.memoryDescription);
+        actions.push(`dropped ${dropped} oldest memories`);
+        current = estimate();
+      }
+
+      // Strategy 3: Drop skills by reverse order
+      if (current > options.tokenBudget && skillSectionIdx !== -1 && loadedSkills.length > 1) {
+        while (loadedSkills.length > 1 && current > options.tokenBudget) {
+          const dropped = loadedSkills.pop()!;
+          actions.push(`dropped skill: ${dropped.name}`);
+          sections[skillSectionIdx] = formatSkills(loadedSkills, options?.maxSkillLength ?? 2000, options?.skillDisclosure);
+          current = estimate();
+        }
+      }
+
+      if (actions.length > 0) {
+        const warning: BudgetWarning = { budget: options.tokenBudget, actual: current, actions };
+        options.onBudgetExceeded?.(warning);
+        options?.logger?.log({
+          timestamp: new Date().toISOString(),
+          level: current > options.tokenBudget ? 'warn' : 'info',
+          phase: 'format',
+          event: 'budget_trimmed',
+          data: warning as unknown as Record<string, unknown>,
+          durationMs: Math.round(performance.now() - start),
+        });
+      } else if (current > options.tokenBudget) {
+        const warning: BudgetWarning = {
+          budget: options.tokenBudget,
+          actual: current,
+          actions: ['budget exceeded by non-trimmable content (identities)'],
+        };
+        options.onBudgetExceeded?.(warning);
+        options?.logger?.log({
+          timestamp: new Date().toISOString(),
+          level: 'warn',
+          phase: 'format',
+          event: 'budget_exceeded_no_action',
+          data: warning as unknown as Record<string, unknown>,
+          durationMs: Math.round(performance.now() - start),
+        });
+      }
+    }
+  }
+
   const result = sections.join('\n\n---\n\n');
 
   options?.logger?.log({
@@ -75,20 +166,35 @@ export function formatContext(ctx: EnrichedContext, options?: FormatOptions): st
   return result;
 }
 
-function formatMemory(memories: MemoryEntry[]): string {
+function formatMemory(memories: MemoryEntry[], description?: string): string {
   const lines = ['## Relevant Memory\n'];
-  for (const m of memories.slice(0, 10)) { // Limit to 10 most relevant
+  if (description) {
+    lines.push(`> ${description}\n`);
+  }
+  for (const m of memories.slice(0, 10)) {
     const date = m.date ? ` (${m.date})` : '';
     lines.push(`- ${m.content}${date}`);
   }
   return lines.join('\n');
 }
 
-function formatSkills(skills: Skill[], maxLength?: number): string {
+function formatTasks(tasks: Task[]): string {
+  const lines = ['## Current Tasks (In Progress)\n'];
+  for (const t of tasks.slice(0, 10)) {
+    const project = t.project ? ` [${t.project}]` : '';
+    const priority = t.priority ? ` (${t.priority})` : '';
+    lines.push(`- ${t.text}${project}${priority}`);
+  }
+  return lines.join('\n');
+}
+
+function formatSkills(skills: Skill[], maxLength?: number, disclosure?: 'full' | 'progressive'): string {
   const lines = ['## Active Skills\n'];
   for (const s of skills) {
     lines.push(`### ${s.name}`);
-    if (s.content) {
+    if (disclosure === 'progressive') {
+      lines.push(s.description);
+    } else if (s.content) {
       if (maxLength != null && s.content.length > maxLength) {
         lines.push(s.content.slice(0, maxLength) + '\n\n[...truncated]');
       } else {
@@ -108,6 +214,24 @@ function formatTools(tools: Tool[]): string {
   return lines.join('\n');
 }
 
+/**
+ * Format tool hints from capabilities that have promptSnippet or promptGuidelines.
+ * Returns empty string if no capabilities have hints.
+ */
+export function formatToolHints(capabilities: Capability[]): string {
+  const withHints = capabilities.filter(c => c.promptSnippet || c.promptGuidelines);
+  if (withHints.length === 0) return '';
+
+  const lines = ['## Tool Hints\n'];
+  for (const cap of withHints) {
+    lines.push(`### ${cap.name}`);
+    if (cap.promptSnippet) lines.push(cap.promptSnippet);
+    if (cap.promptGuidelines) lines.push(`\n> ${cap.promptGuidelines}`);
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
 function formatRouting(routing: RoutingResult): string {
   return `## Model Routing\n\nRecommended model: **${routing.model}** (${routing.reason})`;
 }

package/src/index.ts

@@ -1,8 +1,8 @@
 /**
- * @dot-ai/core v4 — Contracts and types for the dot-ai convention.
+ * @dot-ai/core v6 — Headless Agent framework.
  *
- * dot-ai = contracts (interfaces) + providers (pluggable implementations) + adapters (agent integration).
- * Core defines WHAT, providers define HOW, adapters define WHERE.
+ * dot-ai = extensions (event-driven plugins) + adapters (agent integration).
+ * Everything is an extension. Core orchestrates events, adapters map to agent runtimes.
  */
 
 // ── Types ──
@@ -19,39 +19,57 @@ export type {
   TaskFilter,
   DotAiConfig,
   DebugConfig,
-  ProviderConfig,
   WorkspaceConfig,
+  BudgetWarning,
+  PromptTemplate,
+  ExtensionsConfig,
+  PromptsConfig,
 } from './types.js';
 
-// ── Contracts ──
+// ── Extension Types ──
 export type {
-  MemoryProvider,
-  SkillProvider,
-  IdentityProvider,
-  RoutingProvider,
-  TaskProvider,
-  ToolProvider,
-  ProviderFactory,
-} from './contracts.js';
-
-// ── Engine ──
-export { boot, enrich, learn } from './engine.js';
-export type { Providers, BootCache } from './engine.js';
+  Section,
+  ResourceEntry,
+  ResourcesDiscoverResult,
+  LabelExtractEvent,
+  ContextEnrichEvent,
+  ContextEnrichResult,
+  CollectedSections,
+  RouteEvent,
+  RouteResult,
+  InputEvent,
+  InputResult,
+  CommandParameter,
+  CommandResult,
+  CommandDefinition,
+  ToolDefinition,
+  ExtensionContext,
+  ExtensionEvent,
+  ExtensionTier,
+  ExtensionEventName,
+  LoadedExtension,
+  ExtensionDiagnostic,
+  ToolCallEvent, ToolCallResult,
+  ToolResultEvent,
+  AgentEndEvent,
+  Message,
+  ContextInjectEvent, ContextInjectResult,
+  ContextModifyEvent, ContextModifyResult,
+} from './extension-types.js';
+export { EVENT_TIERS, ADAPTER_CAPABILITIES, TOOL_STRATEGY } from './extension-types.js';
 
-// ── Config ──
-export { loadConfig, resolveConfig, injectRoot } from './config.js';
-export type { ResolvedConfig } from './config.js';
+// ── Extension Runner ──
+export { ExtensionRunner, EventBus } from './extension-runner.js';
 
-// ── Format ──
-export { formatContext } from './format.js';
-export type { FormatOptions } from './format.js';
+// ── Extension API ──
+export type { ExtensionAPI, ExtensionContextV6 } from './extension-api.js';
 
-// ── Logger ──
-export type { LogLevel, LogEntry, Logger } from './logger.js';
-export { NoopLogger, JsonFileLogger, StderrLogger } from './logger.js';
+// ── Extension Loader ──
+export { discoverExtensions, createV6CollectorAPI } from './extension-loader.js';
 
-// ── Loader ──
-export { registerProvider, clearProviders, createProviders } from './loader.js';
+// ── Runtime ──
+export { DotAiRuntime } from './runtime.js';
+export type { RuntimeOptions, ProcessResult, RuntimeDiagnostics } from './runtime.js';
 
 // ── Labels ──
 export { extractLabels, buildVocabulary } from './labels.js';
@@ -59,5 +77,25 @@ export { extractLabels, buildVocabulary } from './labels.js';
 // ── Nodes ──
 export { discoverNodes, parseScanDirs } from './nodes.js';
 
-// ── registerDefaults ──
-export { registerDefaults } from './loader.js';
+// ── Format ──
+export { formatContext, formatToolHints } from './format.js';
+export type { FormatOptions } from './format.js';
+
+// ── Capabilities ──
+export { toolDefinitionToCapability } from './capabilities.js';
+export type { Capability, CapabilityResult } from './capabilities.js';
+
+// ── Logger ──
+export type { LogLevel, LogEntry, Logger } from './logger.js';
+export { NoopLogger, JsonFileLogger, StderrLogger } from './logger.js';
+
+// ── Config ──
+export { loadConfig, migrateConfig } from './config.js';
+
+// ── Package Manager ──
+export { install, remove, listPackages, resolvePackages } from './package-manager.js';
+export type { PackageInfo } from './package-manager.js';
+
+// ── Boot Cache ──
+export { computeChecksum, loadBootCache, writeBootCache, clearBootCache } from './boot-cache.js';
+export type { BootCacheData } from './boot-cache.js';

package/src/logger.ts

@@ -5,7 +5,7 @@ export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
 export interface LogEntry {
   timestamp: string;
   level: LogLevel;
-  phase: 'boot' | 'enrich' | 'learn' | 'format';
+  phase: 'boot' | 'enrich' | 'learn' | 'format' | 'runtime';
   event: string;
   data?: Record<string, unknown>;
   durationMs?: number;

package/src/package-manager.ts

@@ -0,0 +1,119 @@
+import { execSync } from 'node:child_process';
+import { readFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export interface PackageInfo {
+  name: string;
+  version: string;
+  dotAi?: {
+    extensions?: string[];
+    skills?: string[];
+    providers?: string[];
+  };
+}
+
+/**
+ * Install a dot-ai package from npm or git.
+ */
+export async function install(
+  source: string,
+  targetDir: string,
+): Promise<PackageInfo> {
+  const installDir = join(targetDir, '.ai', 'packages');
+  await mkdir(installDir, { recursive: true });
+
+  execSync(`npm install --prefix "${installDir}" "${source}"`, {
+    stdio: 'pipe',
+    timeout: 60000,
+  });
+
+  // Read installed package info
+  const name = source.startsWith('@') || !source.includes('/')
+    ? source.replace(/@[^/]*$/, '')
+    : source;
+  return readPackageInfo(installDir, name);
+}
+
+/**
+ * Remove an installed package.
+ */
+export async function remove(
+  name: string,
+  targetDir: string,
+): Promise<void> {
+  const installDir = join(targetDir, '.ai', 'packages');
+  execSync(`npm uninstall --prefix "${installDir}" "${name}"`, {
+    stdio: 'pipe',
+    timeout: 60000,
+  });
+}
+
+/**
+ * List installed dot-ai packages.
+ */
+export async function listPackages(
+  targetDir: string,
+): Promise<PackageInfo[]> {
+  const installDir = join(targetDir, '.ai', 'packages');
+  const pkgJsonPath = join(installDir, 'package.json');
+
+  try {
+    const raw = await readFile(pkgJsonPath, 'utf-8');
+    const pkg = JSON.parse(raw) as Record<string, unknown>;
+    const deps = pkg.dependencies as Record<string, string> | undefined;
+    if (!deps) return [];
+
+    const packages: PackageInfo[] = [];
+    for (const name of Object.keys(deps)) {
+      try {
+        const info = await readPackageInfo(installDir, name);
+        packages.push(info);
+      } catch {
+        packages.push({ name, version: deps[name] });
+      }
+    }
+    return packages;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Resolve dot-ai manifest from installed packages.
+ */
+export async function resolvePackages(
+  targetDir: string,
+): Promise<{ extensions: string[]; skills: string[]; providers: string[] }> {
+  const packages = await listPackages(targetDir);
+  const result = { extensions: [] as string[], skills: [] as string[], providers: [] as string[] };
+
+  const installDir = join(targetDir, '.ai', 'packages');
+  for (const pkg of packages) {
+    if (!pkg.dotAi) continue;
+    const pkgDir = join(installDir, 'node_modules', pkg.name);
+
+    if (pkg.dotAi.extensions) {
+      result.extensions.push(...pkg.dotAi.extensions.map(e => join(pkgDir, e)));
+    }
+    if (pkg.dotAi.skills) {
+      result.skills.push(...pkg.dotAi.skills.map(s => join(pkgDir, s)));
+    }
+    if (pkg.dotAi.providers) {
+      result.providers.push(...pkg.dotAi.providers.map(p => join(pkgDir, p)));
+    }
+  }
+
+  return result;
+}
+
+async function readPackageInfo(installDir: string, name: string): Promise<PackageInfo> {
+  const pkgPath = join(installDir, 'node_modules', name, 'package.json');
+  const raw = await readFile(pkgPath, 'utf-8');
+  const pkg = JSON.parse(raw) as Record<string, unknown>;
+
+  return {
+    name: pkg.name as string,
+    version: pkg.version as string,
+    dotAi: pkg['dot-ai'] as PackageInfo['dotAi'],
+  };
+}