@soleri/core 9.0.4 → 9.3.0

package/src/domain-packs/types.test.ts

@@ -0,0 +1,144 @@
+/**
+ * Colocated tests for domain-packs/types.ts
+ *
+ * Lighter coverage than __tests__/domain-packs.test.ts — focuses on
+ * edge cases and boundary conditions not covered there.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { validateDomainPack, SEMANTIC_FACADE_NAMES } from './types.js';
+
+function minimalPack(overrides: Record<string, unknown> = {}) {
+  return {
+    name: 'test-pack',
+    version: '1.0.0',
+    domains: ['testing'],
+    ops: [
+      {
+        name: 'op_one',
+        description: 'A test op.',
+        auth: 'read' as const,
+        handler: async () => ({}),
+      },
+    ],
+    ...overrides,
+  };
+}
+
+describe('validateDomainPack', () => {
+  it('accepts pack with optional fields omitted', () => {
+    const result = validateDomainPack(minimalPack());
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects empty name', () => {
+    const result = validateDomainPack(minimalPack({ name: '' }));
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects empty version', () => {
+    const result = validateDomainPack(minimalPack({ version: '' }));
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects empty domains array', () => {
+    const result = validateDomainPack(minimalPack({ domains: [] }));
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects non-object input', () => {
+    expect(validateDomainPack(null).success).toBe(false);
+    expect(validateDomainPack('string').success).toBe(false);
+    expect(validateDomainPack(42).success).toBe(false);
+  });
+
+  it('accepts pack with rules string', () => {
+    const result = validateDomainPack(
+      minimalPack({ rules: '## Token Rules\nUse semantic tokens.' }),
+    );
+    expect(result.success).toBe(true);
+  });
+
+  it('accepts pack with skills array', () => {
+    const result = validateDomainPack(
+      minimalPack({ skills: [{ name: 'my-skill', path: './skills/my-skill.md' }] }),
+    );
+    expect(result.success).toBe(true);
+  });
+
+  it('accepts pack with requires array', () => {
+    const result = validateDomainPack(minimalPack({ requires: ['other-pack'] }));
+    expect(result.success).toBe(true);
+  });
+
+  it('accepts pack with onInstall and onActivate callbacks', () => {
+    const result = validateDomainPack(
+      minimalPack({
+        onInstall: async () => {},
+        onActivate: async () => {},
+      }),
+    );
+    expect(result.success).toBe(true);
+  });
+
+  it('allows non-semantic facade names', () => {
+    const result = validateDomainPack(
+      minimalPack({
+        facades: [{ name: 'design_rules', description: 'Rules.', ops: [] }],
+      }),
+    );
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects each semantic facade name as a pack facade', () => {
+    for (const reserved of ['vault', 'brain', 'memory']) {
+      const result = validateDomainPack(
+        minimalPack({
+          facades: [{ name: reserved, description: 'Collision.', ops: [] }],
+        }),
+      );
+      expect(result.success).toBe(false);
+    }
+  });
+
+  it('rejects duplicate op names with correct error message', () => {
+    const result = validateDomainPack(
+      minimalPack({
+        ops: [
+          { name: 'dup', description: 'A.', auth: 'read', handler: async () => ({}) },
+          { name: 'dup', description: 'B.', auth: 'write', handler: async () => ({}) },
+        ],
+      }),
+    );
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.errors.issues[0].message).toContain('Duplicate op name');
+    }
+  });
+});
+
+describe('SEMANTIC_FACADE_NAMES', () => {
+  it('is a readonly array (TypeScript enforced)', () => {
+    expect(Array.isArray(SEMANTIC_FACADE_NAMES)).toBe(true);
+    expect(SEMANTIC_FACADE_NAMES.length).toBeGreaterThan(0);
+  });
+
+  it('contains all core engine facades', () => {
+    const expected = [
+      'vault',
+      'plan',
+      'brain',
+      'memory',
+      'admin',
+      'curator',
+      'loop',
+      'orchestrate',
+      'control',
+      'cognee',
+      'governance',
+    ];
+    for (const name of expected) {
+      expect(SEMANTIC_FACADE_NAMES).toContain(name);
+    }
+  });
+});

package/src/enforcement/adapters/claude-code.test.ts

@@ -0,0 +1,216 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { ClaudeCodeAdapter } from './claude-code.js';
+import type { EnforcementConfig, EnforcementRule } from '../types.js';
+
+// ─── Test Factories ─────────────────────────────────────────────────
+
+function createRule(overrides: Partial<EnforcementRule> = {}): EnforcementRule {
+  return {
+    id: 'test-rule',
+    description: 'Test rule description',
+    trigger: 'pre-tool-use',
+    action: 'warn',
+    message: 'Test warning message',
+    ...overrides,
+  };
+}
+
+function createConfig(rules: EnforcementRule[]): EnforcementConfig {
+  return { rules };
+}
+
+// ─── ClaudeCodeAdapter ──────────────────────────────────────────────
+
+describe('ClaudeCodeAdapter', () => {
+  let adapter: ClaudeCodeAdapter;
+
+  beforeEach(() => {
+    adapter = new ClaudeCodeAdapter();
+  });
+
+  describe('host', () => {
+    it('should identify as claude-code', () => {
+      expect(adapter.host).toBe('claude-code');
+    });
+  });
+
+  describe('supports', () => {
+    it('should support pre-tool-use trigger', () => {
+      expect(adapter.supports('pre-tool-use')).toBe(true);
+    });
+
+    it('should support post-tool-use trigger', () => {
+      expect(adapter.supports('post-tool-use')).toBe(true);
+    });
+
+    it('should support pre-compact trigger', () => {
+      expect(adapter.supports('pre-compact')).toBe(true);
+    });
+
+    it('should support session-start trigger', () => {
+      expect(adapter.supports('session-start')).toBe(true);
+    });
+
+    it('should support pre-commit trigger', () => {
+      expect(adapter.supports('pre-commit')).toBe(true);
+    });
+
+    it('should not support on-save trigger', () => {
+      expect(adapter.supports('on-save')).toBe(false);
+    });
+  });
+
+  describe('translate', () => {
+    it('should return empty files and skipped when no rules', () => {
+      const result = adapter.translate(createConfig([]));
+      expect(result.host).toBe('claude-code');
+      expect(result.files).toEqual([]);
+      expect(result.skipped).toEqual([]);
+    });
+
+    it('should skip rules with unsupported triggers', () => {
+      const rule = createRule({ id: 'save-rule', trigger: 'on-save' });
+      const result = adapter.translate(createConfig([rule]));
+
+      expect(result.skipped).toHaveLength(1);
+      expect(result.skipped[0]).toEqual({
+        ruleId: 'save-rule',
+        reason: "Trigger 'on-save' not supported",
+      });
+      expect(result.files).toEqual([]);
+    });
+
+    it('should generate settings.json for pre-tool-use with pattern', () => {
+      const rule = createRule({
+        id: 'no-console',
+        trigger: 'pre-tool-use',
+        pattern: 'console\\.log',
+        action: 'warn',
+        message: 'No console.log',
+      });
+      const result = adapter.translate(createConfig([rule]));
+
+      expect(result.files).toHaveLength(1);
+      expect(result.files[0].path).toBe('.claude/settings.json');
+
+      const parsed = JSON.parse(result.files[0].content);
+      expect(parsed.hooks).toHaveLength(1);
+      expect(parsed.hooks[0].event).toBe('PreToolUse');
+      expect(parsed.hooks[0].command).toContain('console\\.log');
+      expect(parsed.hooks[0].command).toContain('WARNING');
+    });
+
+    it('should generate block command for block action', () => {
+      const rule = createRule({
+        id: 'block-secrets',
+        trigger: 'pre-tool-use',
+        pattern: 'API_KEY',
+        action: 'block',
+        message: 'Do not commit secrets',
+      });
+      const result = adapter.translate(createConfig([rule]));
+
+      const parsed = JSON.parse(result.files[0].content);
+      expect(parsed.hooks[0].command).toContain('BLOCKED');
+      expect(parsed.hooks[0].command).toContain('exit 1');
+    });
+
+    it('should generate simple echo command when no pattern', () => {
+      const rule = createRule({
+        id: 'session-check',
+        trigger: 'session-start',
+        message: 'Session started',
+      });
+      const result = adapter.translate(createConfig([rule]));
+
+      const parsed = JSON.parse(result.files[0].content);
+      expect(parsed.hooks[0].event).toBe('SessionStart');
+      expect(parsed.hooks[0].command).toBe('echo "[session-check] Session started"');
+    });
+
+    it('should generate hookify file for pre-commit trigger', () => {
+      const rule = createRule({
+        id: 'no-ai-attribution',
+        trigger: 'pre-commit',
+        pattern: 'Co-Authored-By',
+        message: 'No AI attribution in commits',
+        description: 'Blocks AI co-author lines',
+      });
+      const result = adapter.translate(createConfig([rule]));
+
+      expect(result.files).toHaveLength(1);
+      expect(result.files[0].path).toBe('.claude/hookify.no-ai-attribution.local.md');
+
+      const content = result.files[0].content;
+      expect(content).toContain('name: no-ai-attribution');
+      expect(content).toContain('Blocks AI co-author lines');
+      expect(content).toContain('Pattern: `Co-Authored-By`');
+      expect(content).toContain('No AI attribution in commits');
+    });
+
+    it('should generate hookify file without pattern when none provided', () => {
+      const rule = createRule({
+        id: 'commit-check',
+        trigger: 'pre-commit',
+        description: 'General commit check',
+        message: 'Check before commit',
+      });
+      const result = adapter.translate(createConfig([rule]));
+
+      const content = result.files[0].content;
+      expect(content).toContain('name: commit-check');
+      expect(content).not.toContain('Pattern:');
+    });
+
+    it('should handle mixed rules with hooks and hookify files', () => {
+      const rules = [
+        createRule({ id: 'tool-check', trigger: 'pre-tool-use', pattern: 'rm -rf' }),
+        createRule({ id: 'commit-check', trigger: 'pre-commit' }),
+        createRule({ id: 'unsupported', trigger: 'on-save' }),
+      ];
+      const result = adapter.translate(createConfig(rules));
+
+      expect(result.files).toHaveLength(2);
+      expect(result.skipped).toHaveLength(1);
+
+      const settingsFile = result.files.find((f) => f.path === '.claude/settings.json');
+      const hookFile = result.files.find((f) => f.path.includes('hookify'));
+      expect(settingsFile).toBeDefined();
+      expect(hookFile).toBeDefined();
+    });
+
+    it('should combine multiple hook events into single settings.json', () => {
+      const rules = [
+        createRule({ id: 'rule-1', trigger: 'pre-tool-use', pattern: 'test1' }),
+        createRule({ id: 'rule-2', trigger: 'pre-compact', pattern: 'test2' }),
+        createRule({ id: 'rule-3', trigger: 'session-start', message: 'hello' }),
+      ];
+      const result = adapter.translate(createConfig(rules));
+
+      const settingsFile = result.files.find((f) => f.path === '.claude/settings.json');
+      expect(settingsFile).toBeDefined();
+
+      const parsed = JSON.parse(settingsFile!.content);
+      expect(parsed.hooks).toHaveLength(3);
+      expect(parsed.hooks[0].event).toBe('PreToolUse');
+      expect(parsed.hooks[1].event).toBe('PreCompact');
+      expect(parsed.hooks[2].event).toBe('SessionStart');
+    });
+
+    it('should map post-tool-use to PostToolUse event', () => {
+      const rule = createRule({ id: 'post-check', trigger: 'post-tool-use', pattern: 'error' });
+      const result = adapter.translate(createConfig([rule]));
+
+      const parsed = JSON.parse(result.files[0].content);
+      expect(parsed.hooks[0].event).toBe('PostToolUse');
+    });
+
+    it('should not generate settings.json when only pre-commit rules exist', () => {
+      const rule = createRule({ id: 'commit-only', trigger: 'pre-commit' });
+      const result = adapter.translate(createConfig([rule]));
+
+      const settingsFile = result.files.find((f) => f.path === '.claude/settings.json');
+      expect(settingsFile).toBeUndefined();
+    });
+  });
+});

package/src/enforcement/registry.test.ts

@@ -0,0 +1,258 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { EnforcementRegistry } from './registry.js';
+import { ClaudeCodeAdapter } from './adapters/claude-code.js';
+import type { EnforcementRule } from './types.js';
+
+function makeRule(overrides: Partial<EnforcementRule> = {}): EnforcementRule {
+  return {
+    id: 'test-rule',
+    description: 'Test rule',
+    trigger: 'pre-tool-use',
+    action: 'block',
+    message: 'Blocked',
+    ...overrides,
+  };
+}
+
+describe('EnforcementRegistry', () => {
+  let registry: EnforcementRegistry;
+
+  beforeEach(() => {
+    registry = new EnforcementRegistry();
+  });
+
+  // ─── addRule / getRule ───────────────────────────────────────────
+
+  describe('addRule', () => {
+    it('adds a rule and retrieves it by ID', () => {
+      registry.addRule(makeRule({ id: 'r1' }));
+      expect(registry.getRule('r1')).toBeDefined();
+      expect(registry.getRule('r1')?.id).toBe('r1');
+    });
+
+    it('replaces a rule with the same ID', () => {
+      registry.addRule(makeRule({ id: 'r1', message: 'first' }));
+      registry.addRule(makeRule({ id: 'r1', message: 'second' }));
+      expect(registry.getRules()).toHaveLength(1);
+      expect(registry.getRule('r1')?.message).toBe('second');
+    });
+
+    it('returns undefined for nonexistent rule', () => {
+      expect(registry.getRule('does-not-exist')).toBeUndefined();
+    });
+  });
+
+  // ─── addRules ───────────────────────────────────────────────────
+
+  describe('addRules', () => {
+    it('adds multiple rules at once', () => {
+      registry.addRules([makeRule({ id: 'a' }), makeRule({ id: 'b' })]);
+      expect(registry.getRules()).toHaveLength(2);
+    });
+
+    it('handles empty array', () => {
+      registry.addRules([]);
+      expect(registry.getRules()).toHaveLength(0);
+    });
+  });
+
+  // ─── removeRule ─────────────────────────────────────────────────
+
+  describe('removeRule', () => {
+    it('returns true when rule existed', () => {
+      registry.addRule(makeRule({ id: 'r1' }));
+      expect(registry.removeRule('r1')).toBe(true);
+      expect(registry.getRules()).toHaveLength(0);
+    });
+
+    it('returns false when rule did not exist', () => {
+      expect(registry.removeRule('nonexistent')).toBe(false);
+    });
+  });
+
+  // ─── getEnabledRules / getConfig ────────────────────────────────
+
+  describe('getEnabledRules', () => {
+    it('excludes disabled rules', () => {
+      registry.addRules([makeRule({ id: 'active' }), makeRule({ id: 'disabled', enabled: false })]);
+      const enabled = registry.getEnabledRules();
+      expect(enabled).toHaveLength(1);
+      expect(enabled[0].id).toBe('active');
+    });
+
+    it('includes rules with enabled=undefined (defaults to true)', () => {
+      registry.addRule(makeRule({ id: 'implicit-enabled' }));
+      expect(registry.getEnabledRules()).toHaveLength(1);
+    });
+  });
+
+  describe('getConfig', () => {
+    it('returns config with only enabled rules', () => {
+      registry.addRules([makeRule({ id: 'on' }), makeRule({ id: 'off', enabled: false })]);
+      const config = registry.getConfig();
+      expect(config.rules).toHaveLength(1);
+      expect(config.rules[0].id).toBe('on');
+    });
+  });
+
+  // ─── adapter management ─────────────────────────────────────────
+
+  describe('adapters', () => {
+    it('registers and retrieves an adapter', () => {
+      const adapter = new ClaudeCodeAdapter();
+      registry.registerAdapter(adapter);
+      expect(registry.getAdapter('claude-code')).toBe(adapter);
+    });
+
+    it('lists registered adapter hosts', () => {
+      registry.registerAdapter(new ClaudeCodeAdapter());
+      expect(registry.listAdapters()).toEqual(['claude-code']);
+    });
+
+    it('returns undefined for unregistered host', () => {
+      expect(registry.getAdapter('cursor')).toBeUndefined();
+    });
+  });
+
+  // ─── translate ──────────────────────────────────────────────────
+
+  describe('translate', () => {
+    it('returns skipped rules when no adapter matches', () => {
+      registry.addRule(makeRule({ id: 'r1' }));
+      const result = registry.translate('missing-host');
+      expect(result.host).toBe('missing-host');
+      expect(result.files).toHaveLength(0);
+      expect(result.skipped).toHaveLength(1);
+      expect(result.skipped[0].reason).toContain('No adapter registered');
+    });
+
+    it('delegates to adapter.translate with enabled rules only', () => {
+      registry.addRules([
+        makeRule({ id: 'r1', pattern: 'console\\.log' }),
+        makeRule({ id: 'r2', enabled: false }),
+      ]);
+      registry.registerAdapter(new ClaudeCodeAdapter());
+
+      const result = registry.translate('claude-code');
+      expect(result.host).toBe('claude-code');
+      // Only r1 should be translated (r2 is disabled)
+      expect(result.files.length).toBeGreaterThan(0);
+    });
+  });
+
+  // ─── translateAll ───────────────────────────────────────────────
+
+  describe('translateAll', () => {
+    it('translates for all registered adapters', () => {
+      registry.addRule(makeRule({ id: 'r1', pattern: 'test' }));
+      registry.registerAdapter(new ClaudeCodeAdapter());
+
+      const results = registry.translateAll();
+      expect(results).toHaveLength(1);
+      expect(results[0].host).toBe('claude-code');
+    });
+
+    it('returns empty array when no adapters are registered', () => {
+      registry.addRule(makeRule());
+      expect(registry.translateAll()).toEqual([]);
+    });
+  });
+});
+
+describe('ClaudeCodeAdapter', () => {
+  const adapter = new ClaudeCodeAdapter();
+
+  describe('supports', () => {
+    it('supports pre-tool-use, post-tool-use, pre-compact, session-start, pre-commit', () => {
+      expect(adapter.supports('pre-tool-use')).toBe(true);
+      expect(adapter.supports('post-tool-use')).toBe(true);
+      expect(adapter.supports('pre-compact')).toBe(true);
+      expect(adapter.supports('session-start')).toBe(true);
+      expect(adapter.supports('pre-commit')).toBe(true);
+    });
+
+    it('does not support on-save', () => {
+      expect(adapter.supports('on-save')).toBe(false);
+    });
+  });
+
+  describe('translate', () => {
+    it('creates settings.json for pattern-based pre-tool-use rule', () => {
+      const result = adapter.translate({
+        rules: [makeRule({ id: 'no-console', pattern: 'console\\.log', trigger: 'pre-tool-use' })],
+      });
+
+      const settings = result.files.find((f) => f.path.includes('settings.json'));
+      expect(settings).toBeDefined();
+      const parsed = JSON.parse(settings!.content);
+      expect(parsed.hooks[0].event).toBe('PreToolUse');
+    });
+
+    it('creates hookify file for pre-commit rule', () => {
+      const result = adapter.translate({
+        rules: [makeRule({ id: 'check-debug', trigger: 'pre-commit', pattern: 'debugger' })],
+      });
+
+      const hookFile = result.files.find((f) => f.path.includes('hookify'));
+      expect(hookFile).toBeDefined();
+      expect(hookFile!.content).toContain('name: check-debug');
+    });
+
+    it('generates block command with exit 1 for action=block', () => {
+      const result = adapter.translate({
+        rules: [makeRule({ action: 'block', pattern: 'bad' })],
+      });
+      const settings = result.files.find((f) => f.path.includes('settings.json'));
+      const parsed = JSON.parse(settings!.content);
+      expect(parsed.hooks[0].command).toContain('exit 1');
+      expect(parsed.hooks[0].command).toContain('BLOCKED');
+    });
+
+    it('generates warn command without exit 1 for action=warn', () => {
+      const result = adapter.translate({
+        rules: [makeRule({ action: 'warn', pattern: 'maybe' })],
+      });
+      const settings = result.files.find((f) => f.path.includes('settings.json'));
+      const parsed = JSON.parse(settings!.content);
+      expect(parsed.hooks[0].command).toContain('WARNING');
+      expect(parsed.hooks[0].command).not.toContain('exit 1');
+    });
+
+    it('generates simple echo command for rules without pattern', () => {
+      const result = adapter.translate({
+        rules: [makeRule({ id: 'session-hook', trigger: 'session-start' })],
+      });
+      const settings = result.files.find((f) => f.path.includes('settings.json'));
+      const parsed = JSON.parse(settings!.content);
+      expect(parsed.hooks[0].event).toBe('SessionStart');
+      expect(parsed.hooks[0].command).toContain('echo');
+    });
+
+    it('skips unsupported triggers and reports them', () => {
+      const result = adapter.translate({
+        rules: [makeRule({ id: 'onsave', trigger: 'on-save' })],
+      });
+      expect(result.skipped).toHaveLength(1);
+      expect(result.skipped[0].ruleId).toBe('onsave');
+      expect(result.files).toHaveLength(0);
+    });
+
+    it('handles empty rules config', () => {
+      const result = adapter.translate({ rules: [] });
+      expect(result.files).toHaveLength(0);
+      expect(result.skipped).toHaveLength(0);
+    });
+
+    it('handles mix of supported and unsupported triggers', () => {
+      const result = adapter.translate({
+        rules: [
+          makeRule({ id: 'ok', trigger: 'pre-tool-use', pattern: 'test' }),
+          makeRule({ id: 'bad', trigger: 'on-save' }),
+        ],
+      });
+      expect(result.files.length).toBeGreaterThan(0);
+      expect(result.skipped).toHaveLength(1);
+      expect(result.skipped[0].ruleId).toBe('bad');
+    });
+  });
+});

package/src/engine/bin/soleri-engine.ts

@@ -19,6 +19,9 @@ import { createAgentRuntime } from '../../runtime/runtime.js';
 import { registerEngine } from '../register-engine.js';
 import { createCoreOps } from '../core-ops.js';
 import { seedDefaultPlaybooks } from '../../playbooks/playbook-seeder.js';
+import { agentVaultPath } from '../../paths.js';
+import { checkForUpdate } from '../../update-check.js';
+import { syncSkillsToClaudeCode } from '../../skills/sync-skills.js';
 import type { AgentIdentityConfig } from '../core-ops.js';
 
 // ─── Parse CLI args ───────────────────────────────────────────────────
@@ -65,11 +68,11 @@ async function main(): Promise<void> {
   console.error(`${tag} Agent: ${config.name} (${agentId})`);
   console.error(`${tag} Format: file-tree`);
 
-  // 2. Resolve vault path
+  // 2. Resolve vault path (default: ~/.soleri/{agentId}/vault.db)
   const engineConfig = (config.engine ?? {}) as Record<string, unknown>;
   const vaultPath = engineConfig.vault
     ? resolve((engineConfig.vault as string).replace(/^~/, homedir()))
-    : join(homedir(), `.${agentId}`, 'vault.db');
+    : agentVaultPath(agentId);
 
   // 3. Create runtime (with persona from agent.yaml if present)
   const personaConfig = config.persona as Record<string, unknown> | undefined;
@@ -125,7 +128,9 @@ async function main(): Promise<void> {
         }
       }
     } catch (err) {
-      console.error(`${tag} Warning: post-connection indexing failed: ${err instanceof Error ? err.message : String(err)}`);
+      console.error(
+        `${tag} Warning: post-connection indexing failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
     }
   }
 
@@ -158,6 +163,18 @@ async function main(): Promise<void> {
       .join(', ')})`,
   );
 
+  // 6b. Auto-sync skills to ~/.claude/commands/
+  const skillsDir = join(agentDir, 'skills');
+  if (existsSync(skillsDir)) {
+    const syncResult = syncSkillsToClaudeCode([skillsDir], config.name as string);
+    const total = syncResult.installed.length + syncResult.updated.length;
+    if (total > 0) {
+      console.error(
+        `${tag} Skills synced: ${syncResult.installed.length} new, ${syncResult.updated.length} updated`,
+      );
+    }
+  }
+
   // 7. Load domain packs
   const packs = (config.packs ?? []) as Array<{ name: string; package: string; version?: string }>;
   const loadedPacks: Array<{ name: string; facades?: Array<{ name: string; ops: unknown[] }> }> =
@@ -249,7 +266,16 @@ async function main(): Promise<void> {
 
   console.error(`${tag} Engine ready — listening on stdio`);
 
-  // 14. Graceful shutdown
+  // 14. Check for updates (fire-and-forget — never blocks, never throws)
+  const enginePkgPath = new URL('../../../package.json', import.meta.url);
+  try {
+    const enginePkg = JSON.parse(readFileSync(enginePkgPath, 'utf-8'));
+    checkForUpdate(agentId, enginePkg.version ?? '0.0.0').catch(() => {});
+  } catch {
+    // package.json not readable — skip update check silently
+  }
+
+  // 15. Graceful shutdown
   const shutdown = () => {
     console.error(`${tag} Shutting down...`);
     runtime.close();