@soleri/core 9.5.0 → 9.7.0

package/src/session/compaction-policy.ts

@@ -0,0 +1,66 @@
+/**
+ * Session Compaction Policy — types and defaults for session rotation.
+ *
+ * Three thresholds determine when a session should be compacted:
+ * - maxRuns: tool call / interaction count
+ * - maxInputTokens: cumulative input token count
+ * - maxAge: wall-clock duration (ISO 8601 duration string, e.g. '72h')
+ */
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/** Policy thresholds — all optional, merged from three levels. */
+export interface CompactionPolicy {
+  /** Maximum number of runs (tool calls / interactions) before compaction. */
+  maxRuns?: number;
+  /** Maximum cumulative input tokens before compaction. */
+  maxInputTokens?: number;
+  /** Maximum wall-clock age as an ISO 8601-ish duration string (e.g. '72h', '30m', '7d'). */
+  maxAge?: string;
+}
+
+/** Result of evaluating whether compaction is needed. */
+export interface CompactionResult {
+  /** Whether compaction should happen. */
+  compact: boolean;
+  /** Human-readable reason (empty string when compact is false). */
+  reason: string;
+  /** Pre-rendered handoff markdown (empty string when compact is false). */
+  handoff: string;
+}
+
+/** State snapshot of the current session, used for evaluation. */
+export interface SessionState {
+  /** Number of runs (tool calls) so far. */
+  runCount: number;
+  /** Cumulative input tokens consumed. */
+  inputTokens: number;
+  /** ISO 8601 timestamp when the session started. */
+  startedAt: string;
+}
+
+/** Structured handoff note persisted on rotation. */
+export interface HandoffNote {
+  /** ISO 8601 timestamp when the session was rotated. */
+  rotatedAt: string;
+  /** Why the session was rotated. */
+  reason: string;
+  /** Description of work in progress at rotation time. */
+  inProgress: string;
+  /** Key decisions made during the session. */
+  keyDecisions: string[];
+  /** Files modified during the session. */
+  filesModified: string[];
+}
+
+// =============================================================================
+// ENGINE DEFAULTS
+// =============================================================================
+
+export const ENGINE_DEFAULTS: Required<CompactionPolicy> = {
+  maxRuns: 200,
+  maxInputTokens: 2_000_000,
+  maxAge: '72h',
+};

package/src/session/compaction.test.ts

@@ -0,0 +1,259 @@
+/**
+ * Session Compaction — colocated contract tests.
+ *
+ * Tests for:
+ * - CompactionEvaluator (shouldCompact)
+ * - PolicyResolver (resolvePolicy)
+ * - HandoffRenderer (renderHandoff)
+ * - Duration parser (parseDuration)
+ */
+
+import { describe, it, expect } from 'vitest';
+import { shouldCompact, parseDuration } from './compaction-evaluator.js';
+import { resolvePolicy } from './policy-resolver.js';
+import { renderHandoff } from './handoff-renderer.js';
+import { ENGINE_DEFAULTS } from './compaction-policy.js';
+import type { SessionState, HandoffNote } from './compaction-policy.js';
+
+// =============================================================================
+// parseDuration
+// =============================================================================
+
+describe('parseDuration', () => {
+  it('parses hours', () => {
+    expect(parseDuration('72h')).toBe(72 * 3_600_000);
+  });
+
+  it('parses minutes', () => {
+    expect(parseDuration('30m')).toBe(30 * 60_000);
+  });
+
+  it('parses days', () => {
+    expect(parseDuration('7d')).toBe(7 * 86_400_000);
+  });
+
+  it('parses seconds', () => {
+    expect(parseDuration('120s')).toBe(120_000);
+  });
+
+  it('parses milliseconds', () => {
+    expect(parseDuration('500ms')).toBe(500);
+  });
+
+  it('returns undefined for invalid input', () => {
+    expect(parseDuration('invalid')).toBeUndefined();
+    expect(parseDuration('')).toBeUndefined();
+    expect(parseDuration('72x')).toBeUndefined();
+  });
+});
+
+// =============================================================================
+// shouldCompact — evaluator
+// =============================================================================
+
+describe('shouldCompact', () => {
+  const baseSession: SessionState = {
+    runCount: 10,
+    inputTokens: 50_000,
+    startedAt: new Date().toISOString(),
+  };
+
+  it('returns false when no thresholds are breached', () => {
+    const result = shouldCompact(baseSession, {
+      maxRuns: 200,
+      maxInputTokens: 2_000_000,
+      maxAge: '72h',
+    });
+    expect(result.compact).toBe(false);
+    expect(result.reason).toBe('');
+  });
+
+  it('triggers on maxRuns', () => {
+    const session = { ...baseSession, runCount: 200 };
+    const result = shouldCompact(session, { maxRuns: 200 });
+    expect(result.compact).toBe(true);
+    expect(result.reason).toContain('Run count');
+    expect(result.reason).toContain('200');
+  });
+
+  it('triggers on maxRuns when exceeded', () => {
+    const session = { ...baseSession, runCount: 250 };
+    const result = shouldCompact(session, { maxRuns: 200 });
+    expect(result.compact).toBe(true);
+  });
+
+  it('triggers on maxInputTokens', () => {
+    const session = { ...baseSession, inputTokens: 2_500_000 };
+    const result = shouldCompact(session, { maxInputTokens: 2_000_000 });
+    expect(result.compact).toBe(true);
+    expect(result.reason).toContain('Input tokens');
+  });
+
+  it('triggers on maxAge', () => {
+    const startedAt = new Date(Date.now() - 80 * 3_600_000).toISOString(); // 80 hours ago
+    const session = { ...baseSession, startedAt };
+    const result = shouldCompact(session, { maxAge: '72h' });
+    expect(result.compact).toBe(true);
+    expect(result.reason).toContain('Session age');
+  });
+
+  it('returns first triggered threshold (maxRuns before maxInputTokens)', () => {
+    const session: SessionState = {
+      runCount: 300,
+      inputTokens: 3_000_000,
+      startedAt: new Date(Date.now() - 100 * 3_600_000).toISOString(),
+    };
+    const result = shouldCompact(session, {
+      maxRuns: 200,
+      maxInputTokens: 2_000_000,
+      maxAge: '72h',
+    });
+    expect(result.compact).toBe(true);
+    expect(result.reason).toContain('Run count');
+  });
+
+  it('skips undefined thresholds', () => {
+    const result = shouldCompact(baseSession, {});
+    expect(result.compact).toBe(false);
+  });
+
+  it('handles invalid maxAge gracefully', () => {
+    const result = shouldCompact(baseSession, { maxAge: 'bogus' });
+    expect(result.compact).toBe(false);
+  });
+
+  it('accepts custom now parameter for age calculation', () => {
+    const startedAt = '2026-01-01T00:00:00.000Z';
+    const now = new Date('2026-01-04T00:00:00.000Z'); // 3 days later
+    const session = { ...baseSession, startedAt };
+    const result = shouldCompact(session, { maxAge: '2d' }, now);
+    expect(result.compact).toBe(true);
+  });
+});
+
+// =============================================================================
+// resolvePolicy — three-level merge
+// =============================================================================
+
+describe('resolvePolicy', () => {
+  it('returns engine defaults when no overrides', () => {
+    const policy = resolvePolicy();
+    expect(policy).toEqual(ENGINE_DEFAULTS);
+  });
+
+  it('agent config overrides engine defaults', () => {
+    const policy = resolvePolicy({ maxRuns: 100 });
+    expect(policy.maxRuns).toBe(100);
+    expect(policy.maxInputTokens).toBe(ENGINE_DEFAULTS.maxInputTokens);
+    expect(policy.maxAge).toBe(ENGINE_DEFAULTS.maxAge);
+  });
+
+  it('adapter defaults override engine defaults', () => {
+    const policy = resolvePolicy(undefined, { maxInputTokens: 1_000_000 });
+    expect(policy.maxInputTokens).toBe(1_000_000);
+    expect(policy.maxRuns).toBe(ENGINE_DEFAULTS.maxRuns);
+  });
+
+  it('agent config overrides adapter defaults', () => {
+    const policy = resolvePolicy({ maxAge: '24h' }, { maxAge: '48h' });
+    expect(policy.maxAge).toBe('24h');
+  });
+
+  it('merges individual fields from different levels', () => {
+    const policy = resolvePolicy({ maxRuns: 50 }, { maxInputTokens: 500_000, maxAge: '12h' });
+    expect(policy.maxRuns).toBe(50); // from agent
+    expect(policy.maxInputTokens).toBe(500_000); // from adapter
+    expect(policy.maxAge).toBe('12h'); // from adapter
+  });
+});
+
+// =============================================================================
+// renderHandoff
+// =============================================================================
+
+describe('renderHandoff', () => {
+  it('renders complete handoff note', () => {
+    const note: HandoffNote = {
+      rotatedAt: '2026-03-27T12:00:00.000Z',
+      reason: 'Run count (200) reached threshold (200)',
+      inProgress: 'Implementing session compaction policies',
+      keyDecisions: ['Used three-level merge for policy resolution', 'ISO 8601 for timestamps'],
+      filesModified: [
+        'packages/core/src/session/compaction-policy.ts',
+        'packages/core/src/index.ts',
+      ],
+    };
+
+    const md = renderHandoff(note);
+    expect(md).toContain('# Session Handoff');
+    expect(md).toContain('**Rotated:** 2026-03-27T12:00:00.000Z');
+    expect(md).toContain('**Reason:** Run count');
+    expect(md).toContain('## In Progress');
+    expect(md).toContain('Implementing session compaction policies');
+    expect(md).toContain('## Key Decisions');
+    expect(md).toContain('- Used three-level merge');
+    expect(md).toContain('## Files Modified');
+    expect(md).toContain('- `packages/core/src/session/compaction-policy.ts`');
+  });
+
+  it('omits In Progress section when empty', () => {
+    const note: HandoffNote = {
+      rotatedAt: '2026-03-27T12:00:00.000Z',
+      reason: 'Token threshold',
+      inProgress: '',
+      keyDecisions: ['Something'],
+      filesModified: [],
+    };
+
+    const md = renderHandoff(note);
+    expect(md).not.toContain('## In Progress');
+    expect(md).toContain('## Key Decisions');
+  });
+
+  it('omits Key Decisions section when empty', () => {
+    const note: HandoffNote = {
+      rotatedAt: '2026-03-27T12:00:00.000Z',
+      reason: 'Age threshold',
+      inProgress: 'Working on X',
+      keyDecisions: [],
+      filesModified: [],
+    };
+
+    const md = renderHandoff(note);
+    expect(md).toContain('## In Progress');
+    expect(md).not.toContain('## Key Decisions');
+    expect(md).not.toContain('## Files Modified');
+  });
+
+  it('omits Files Modified section when empty', () => {
+    const note: HandoffNote = {
+      rotatedAt: '2026-03-27T12:00:00.000Z',
+      reason: 'Threshold',
+      inProgress: '',
+      keyDecisions: [],
+      filesModified: [],
+    };
+
+    const md = renderHandoff(note);
+    expect(md).not.toContain('## In Progress');
+    expect(md).not.toContain('## Key Decisions');
+    expect(md).not.toContain('## Files Modified');
+    // Should still have header and metadata
+    expect(md).toContain('# Session Handoff');
+    expect(md).toContain('**Rotated:**');
+    expect(md).toContain('**Reason:**');
+  });
+
+  it('ends with a trailing newline', () => {
+    const note: HandoffNote = {
+      rotatedAt: '2026-03-27T12:00:00.000Z',
+      reason: 'Test',
+      inProgress: '',
+      keyDecisions: [],
+      filesModified: [],
+    };
+
+    const md = renderHandoff(note);
+    expect(md.endsWith('\n')).toBe(true);
+  });
+});

package/src/session/handoff-renderer.ts

@@ -0,0 +1,56 @@
+/**
+ * Handoff Renderer — converts a HandoffNote into markdown for injection
+ * into the next session's context.
+ *
+ * Omits empty sections gracefully.
+ */
+
+import type { HandoffNote } from './compaction-policy.js';
+
+/**
+ * Render a HandoffNote as markdown.
+ *
+ * Sections:
+ * - Session Handoff (header)
+ * - Rotated At
+ * - Reason
+ * - In Progress
+ * - Key Decisions
+ * - Files Modified
+ *
+ * Empty sections are omitted entirely.
+ */
+export function renderHandoff(note: HandoffNote): string {
+  const lines: string[] = ['# Session Handoff', ''];
+
+  lines.push(`**Rotated:** ${note.rotatedAt}`);
+  lines.push(`**Reason:** ${note.reason}`);
+  lines.push('');
+
+  if (note.inProgress) {
+    lines.push('## In Progress');
+    lines.push('');
+    lines.push(note.inProgress);
+    lines.push('');
+  }
+
+  if (note.keyDecisions.length > 0) {
+    lines.push('## Key Decisions');
+    lines.push('');
+    for (const decision of note.keyDecisions) {
+      lines.push(`- ${decision}`);
+    }
+    lines.push('');
+  }
+
+  if (note.filesModified.length > 0) {
+    lines.push('## Files Modified');
+    lines.push('');
+    for (const file of note.filesModified) {
+      lines.push(`- \`${file}\``);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n').trimEnd() + '\n';
+}

package/src/session/index.ts

@@ -0,0 +1,12 @@
+// ─── Session Compaction ─────────────────────────────────────────────
+export type {
+  CompactionPolicy,
+  CompactionResult,
+  SessionState,
+  HandoffNote,
+} from './compaction-policy.js';
+export { ENGINE_DEFAULTS } from './compaction-policy.js';
+
+export { shouldCompact, parseDuration } from './compaction-evaluator.js';
+export { resolvePolicy } from './policy-resolver.js';
+export { renderHandoff } from './handoff-renderer.js';

package/src/session/policy-resolver.ts

@@ -0,0 +1,34 @@
+/**
+ * Policy Resolver — three-level merge for compaction policies.
+ *
+ * Merge order (highest to lowest priority):
+ *   1. Agent config (agent.yaml → engine.compactionPolicy)
+ *   2. Adapter defaults (runtime adapter may provide defaults)
+ *   3. Engine defaults (hardcoded fallback)
+ *
+ * Individual fields override — not whole-object replacement.
+ */
+
+import type { CompactionPolicy } from './compaction-policy.js';
+import { ENGINE_DEFAULTS } from './compaction-policy.js';
+
+/**
+ * Resolve a final CompactionPolicy by merging three levels.
+ *
+ * Each level can provide partial overrides. Fields from higher-priority
+ * levels win over lower-priority ones. Missing fields fall through to
+ * the next level, bottoming out at ENGINE_DEFAULTS.
+ */
+export function resolvePolicy(
+  agentConfig?: Partial<CompactionPolicy>,
+  adapterDefaults?: Partial<CompactionPolicy>,
+): Required<CompactionPolicy> {
+  return {
+    maxRuns: agentConfig?.maxRuns ?? adapterDefaults?.maxRuns ?? ENGINE_DEFAULTS.maxRuns,
+    maxInputTokens:
+      agentConfig?.maxInputTokens ??
+      adapterDefaults?.maxInputTokens ??
+      ENGINE_DEFAULTS.maxInputTokens,
+    maxAge: agentConfig?.maxAge ?? adapterDefaults?.maxAge ?? ENGINE_DEFAULTS.maxAge,
+  };
+}

package/src/skills/sync-skills.ts

@@ -7,12 +7,17 @@
  */
 
 import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
+import type { SkillMetadata, SourceType } from '../packs/types.js';
+import { classifyTrust } from './trust-classifier.js';
+import { checkVersionCompat } from '../packs/resolver.js';
 
 export interface SkillEntry {
   name: string;
   sourcePath: string;
+  /** Trust and source metadata (populated during classification) */
+  metadata?: SkillMetadata;
 }
 
 export interface SyncResult {
@@ -22,6 +27,27 @@ export interface SyncResult {
   failed: string[];
 }
 
+/** Error thrown when a skill requires approval due to scripts trust level */
+export class ApprovalRequiredError extends Error {
+  readonly skillName: string;
+  readonly trust: 'scripts';
+  readonly inventory: SkillMetadata['inventory'];
+
+  constructor(skillName: string, inventory: SkillMetadata['inventory']) {
+    super(
+      `Skill "${skillName}" contains executable scripts and requires explicit approval. ` +
+        `Scripts found: ${inventory
+          .filter((i) => i.kind === 'script')
+          .map((i) => i.path)
+          .join(', ')}`,
+    );
+    this.name = 'ApprovalRequiredError';
+    this.skillName = skillName;
+    this.trust = 'scripts';
+    this.inventory = inventory;
+  }
+}
+
 /** Discover skill files (SKILL.md) in skills directories */
 export function discoverSkills(skillsDirs: string[]): SkillEntry[] {
   const skills: SkillEntry[] = [];
@@ -103,3 +129,90 @@ export function syncSkillsToClaudeCode(skillsDirs: string[], agentName?: string)
 
   return result;
 }
+
+// =============================================================================
+// TRUST CLASSIFICATION & SOURCE TRACKING
+// =============================================================================
+
+/**
+ * Check engine version compatibility for a skill.
+ * Returns 'compatible', 'unknown' (no version specified), or 'invalid'.
+ */
+export function checkSkillCompatibility(
+  engineVersion?: string,
+  currentVersion?: string,
+): 'compatible' | 'unknown' | 'invalid' {
+  if (!engineVersion) return 'unknown';
+  if (!currentVersion) return 'unknown';
+  return checkVersionCompat(currentVersion, engineVersion) ? 'compatible' : 'invalid';
+}
+
+/**
+ * Infer the source type for a skill based on its directory path.
+ */
+function inferSourceType(skillDir: string): SourceType {
+  if (skillDir.includes('node_modules')) return 'npm';
+  if (skillDir.includes('.soleri') || skillDir.includes('.salvador')) return 'builtin';
+  return 'local';
+}
+
+/**
+ * Read engine version from a skill's SKILL.md frontmatter.
+ * Looks for `engine:` or `engineVersion:` in YAML frontmatter.
+ */
+function readSkillEngineVersion(skillPath: string): string | undefined {
+  try {
+    const content = readFileSync(skillPath, 'utf-8');
+    const fmStart = content.indexOf('---');
+    if (fmStart !== 0) return undefined;
+    const fmEnd = content.indexOf('---', 3);
+    if (fmEnd === -1) return undefined;
+    const fm = content.slice(3, fmEnd);
+    // eslint-disable-next-line no-control-regex
+    const match = fm.match(/^(?:engine|engineVersion)\s*:\s*["']?([^"'\n]+)["']?/m);
+    return match?.[1]?.trim();
+  } catch {
+    return undefined;
+  }
+}
+
+export interface ClassifySkillsOptions {
+  /** Current engine version for compatibility checking */
+  currentEngineVersion?: string;
+  /** Skills that have been explicitly approved for scripts trust level */
+  approvedScripts?: Set<string>;
+}
+
+/**
+ * Classify skills with trust levels and source tracking.
+ * Enriches SkillEntry[] with metadata. Throws ApprovalRequiredError
+ * for skills with 'scripts' trust unless explicitly approved.
+ */
+export function classifySkills(
+  skills: SkillEntry[],
+  options: ClassifySkillsOptions = {},
+): SkillEntry[] {
+  return skills.map((skill) => {
+    const skillDir = dirname(skill.sourcePath);
+    const { trust, inventory } = classifyTrust(skillDir);
+
+    // Approval gate for scripts
+    if (trust === 'scripts' && !options.approvedScripts?.has(skill.name)) {
+      throw new ApprovalRequiredError(skill.name, inventory);
+    }
+
+    const engineVersion = readSkillEngineVersion(skill.sourcePath);
+    const sourceType = inferSourceType(skillDir);
+    const compatibility = checkSkillCompatibility(engineVersion, options.currentEngineVersion);
+
+    const metadata: SkillMetadata = {
+      trust,
+      source: { type: sourceType, uri: skillDir },
+      compatibility,
+      engineVersion,
+      inventory,
+    };
+
+    return { ...skill, metadata };
+  });
+}