@soleri/core 9.14.4 → 9.16.7

package/src/runtime/capture-ops.ts

@@ -30,42 +30,56 @@ export function createCaptureOps(runtime: AgentRuntime): OpDefinition[] {
       description:
         'Batch-capture knowledge entries with governance gating and auto-enrichment via TF-IDF tagging.',
       auth: 'write',
-      schema: z.object({
-        projectPath: z.string().optional().default('.'),
-        tier: z
-          .enum(['agent', 'project', 'team'])
-          .optional()
-          .describe('Manual tier override. If omitted, tier is auto-detected from content.'),
-        entries: coerceArray(
-          z.object({
-            id: z.string().optional(),
-            type: z
-              .enum([
-                'pattern',
-                'anti-pattern',
-                'rule',
-                'playbook',
-                'workflow',
-                'principle',
-                'reference',
-              ])
-              .describe('Entry type'),
-            domain: z.string(),
-            title: z.string(),
-            severity: z.enum(['critical', 'warning', 'info']).optional().default('info'),
-            description: z.string(),
-            tags: z.array(z.string()).optional().default([]),
-            context: z.string().optional(),
-            example: z.string().optional(),
-            counterExample: z.string().optional(),
-            why: z.string().optional(),
-            tier: z
-              .enum(['agent', 'project', 'team'])
-              .optional()
-              .describe('Per-entry tier override. Falls back to top-level tier, then auto-detect.'),
-          }),
-        ),
-      }),
+      schema: z.preprocess(
+        (val) => {
+          // Auto-wrap flat entry fields into { entries: [val] } so callers don't need the wrapper
+          if (val !== null && typeof val === 'object' && !Array.isArray(val)) {
+            const obj = val as Record<string, unknown>;
+            if (obj.entries === undefined && (obj.type !== undefined || obj.title !== undefined)) {
+              return { entries: [obj] };
+            }
+          }
+          return val;
+        },
+        z.object({
+          projectPath: z.string().optional().default('.'),
+          tier: z
+            .enum(['agent', 'project', 'team'])
+            .optional()
+            .describe('Manual tier override. If omitted, tier is auto-detected from content.'),
+          entries: coerceArray(
+            z.object({
+              id: z.string().optional(),
+              type: z
+                .enum([
+                  'pattern',
+                  'anti-pattern',
+                  'rule',
+                  'playbook',
+                  'workflow',
+                  'principle',
+                  'reference',
+                ])
+                .describe('Entry type'),
+              domain: z.string(),
+              title: z.string(),
+              severity: z.enum(['critical', 'warning', 'info']).optional().default('info'),
+              description: z.string(),
+              tags: z.array(z.string()).optional().default([]),
+              context: z.string().optional(),
+              example: z.string().optional(),
+              counterExample: z.string().optional(),
+              why: z.string().optional(),
+              tier: z
+                .enum(['agent', 'project', 'team'])
+                .optional()
+                .describe(
+                  'Per-entry tier override. Falls back to top-level tier, then auto-detect.',
+                ),
+            }),
+          ),
+        }),
+      ),
       handler: async (params) => {
         const projectPath = (params.projectPath as string | undefined) ?? '.';
         const topTier = params.tier as ScopeTier | undefined;
@@ -326,10 +340,13 @@ export function createCaptureOps(runtime: AgentRuntime): OpDefinition[] {
             'principle',
             'reference',
           ])
-          .describe('Entry type'),
-        domain: z.string(),
+          .optional()
+          .default('pattern')
+          .describe('Entry type (default: "pattern")'),
+        domain: z.string().optional().default('general'),
         title: z.string(),
-        description: z.string(),
+        description: z.string().optional().describe('Knowledge description (alias: content)'),
+        content: z.string().optional().describe('Alias for description'),
         tags: z.array(z.string()).optional().default([]),
         tier: z
           .enum(['agent', 'project', 'team'])
@@ -338,10 +355,13 @@ export function createCaptureOps(runtime: AgentRuntime): OpDefinition[] {
       }),
       handler: async (params) => {
         const projectPath = (params.projectPath as string | undefined) ?? '.';
-        const entryType = params.type as string;
-        const domain = params.domain as string;
+        const entryType = (params.type as string | undefined) ?? 'pattern';
+        const domain = (params.domain as string | undefined) ?? 'general';
         const title = params.title as string;
-        const description = params.description as string;
+        const description =
+          (params.description as string | undefined) ??
+          (params.content as string | undefined) ??
+          '';
         const tags = (params.tags as string[] | undefined) ?? [];
         const manualTier = params.tier as ScopeTier | undefined;
 
@@ -405,6 +425,15 @@ export function createCaptureOps(runtime: AgentRuntime): OpDefinition[] {
                   result.reviewNote =
                     'Low confidence scope detection — consider reviewing tier assignment';
                 }
+                const PLANNING_TYPES = new Set(['anti-pattern', 'pattern']);
+                const PLANNING_TAGS = new Set(['planning-gate', 'rules', 'quality']);
+                const hasPlanningType = PLANNING_TYPES.has(mappedType);
+                const hasPlanningTag = tags.some((t) => PLANNING_TAGS.has(t));
+                if (hasPlanningType || hasPlanningTag) {
+                  result.planningNote =
+                    'This entry type influences planning but has no content body (context/example/why). ' +
+                    'Use capture_knowledge to add those fields — without them, the orchestrator cannot apply this rule during planning.';
+                }
                 // Fire-and-forget markdown sync
                 fireAndForgetSync(
                   {
@@ -566,10 +595,13 @@ export function createCaptureOps(runtime: AgentRuntime): OpDefinition[] {
         'Record feedback on search results to improve future ranking via brain learning.',
       auth: 'write',
       schema: z.object({
-        query: z.string(),
-        entryId: z.string(),
-        helpful: z.boolean(),
-        context: z.string().optional(),
+        query: z.string().describe('The search query that produced this result (required)'),
+        entryId: z.string().describe('ID of the vault entry being rated (required)'),
+        helpful: z.boolean().describe('Whether the result was helpful — true or false (required)'),
+        context: z
+          .string()
+          .optional()
+          .describe('Optional context about why it was or was not helpful'),
       }),
       handler: async (params) => {
         const query = params.query as string;

package/src/runtime/chain-ops.test.ts

@@ -25,27 +25,6 @@ const VALID_CHAIN = {
 };
 
 describe('createChainOps', () => {
-  it('returns exactly 5 ops', () => {
-    const ops = createChainOps(mockRuntime());
-    expect(ops).toHaveLength(5);
-    expect(ops.map((o) => o.name)).toEqual([
-      'chain_execute',
-      'chain_status',
-      'chain_resume',
-      'chain_list',
-      'chain_step_approve',
-    ]);
-  });
-
-  it('assigns correct auth levels', () => {
-    const ops = captureOps(createChainOps(mockRuntime()));
-    expect(ops.get('chain_execute')!.auth).toBe('write');
-    expect(ops.get('chain_status')!.auth).toBe('read');
-    expect(ops.get('chain_resume')!.auth).toBe('write');
-    expect(ops.get('chain_list')!.auth).toBe('read');
-    expect(ops.get('chain_step_approve')!.auth).toBe('write');
-  });
-
   describe('chain_execute', () => {
     it('calls chainRunner.execute with chain def and input', async () => {
       const rt = mockRuntime();

package/src/runtime/facades/admin-facade.test.ts

@@ -108,40 +108,6 @@ describe('createAdminFacadeOps', () => {
     ops = createAdminFacadeOps(runtime);
   });
 
-  it('returns inline ops (llm_rotate, llm_call, render_prompt, list_templates)', () => {
-    const names = ops.map((o) => o.name);
-    expect(names).toContain('llm_rotate');
-    expect(names).toContain('llm_call');
-    expect(names).toContain('render_prompt');
-    expect(names).toContain('list_templates');
-  });
-
-  it('includes satellite ops from admin-ops', () => {
-    const names = ops.map((o) => o.name);
-    expect(names).toContain('admin_health');
-    expect(names).toContain('admin_diagnostic');
-    expect(names).toContain('admin_config');
-  });
-
-  it('includes satellite ops from admin-extra-ops', () => {
-    const names = ops.map((o) => o.name);
-    expect(names).toContain('admin_telemetry');
-    expect(names).toContain('admin_permissions');
-    expect(names).toContain('admin_vault_analytics');
-  });
-
-  it('includes satellite ops from admin-setup-ops', () => {
-    const names = ops.map((o) => o.name);
-    expect(names).toContain('admin_inject_claude_md');
-    expect(names).toContain('admin_setup_global');
-    expect(names).toContain('admin_check_persistence');
-  });
-
-  it('includes session briefing ops', () => {
-    const names = ops.map((o) => o.name);
-    expect(names).toContain('session_briefing');
-  });
-
   describe('llm_rotate', () => {
     it('rotates openai key pool', async () => {
       const result = (await findOp(ops, 'llm_rotate').handler({

package/src/runtime/facades/agency-facade.test.ts

@@ -40,45 +40,6 @@ describe('createAgencyFacadeOps', () => {
     ops = createAgencyFacadeOps(runtime);
   });
 
-  it('returns all expected ops', () => {
-    const names = ops.map((o) => o.name);
-    expect(names).toEqual([
-      'agency_enable',
-      'agency_disable',
-      'agency_status',
-      'agency_config',
-      'agency_scan_file',
-      'agency_warnings',
-      'agency_surface_patterns',
-      'agency_clarify',
-      'agency_suggestions',
-      'agency_rich_clarify',
-      'agency_suppress_warning',
-      'agency_unsuppress_warning',
-      'agency_dismiss_pattern',
-      'agency_notifications',
-      'agency_full_status',
-    ]);
-  });
-
-  it('assigns correct auth levels', () => {
-    expect(findOp(ops, 'agency_enable').auth).toBe('write');
-    expect(findOp(ops, 'agency_disable').auth).toBe('write');
-    expect(findOp(ops, 'agency_status').auth).toBe('read');
-    expect(findOp(ops, 'agency_config').auth).toBe('write');
-    expect(findOp(ops, 'agency_scan_file').auth).toBe('read');
-    expect(findOp(ops, 'agency_warnings').auth).toBe('read');
-    expect(findOp(ops, 'agency_surface_patterns').auth).toBe('read');
-    expect(findOp(ops, 'agency_clarify').auth).toBe('read');
-    expect(findOp(ops, 'agency_suggestions').auth).toBe('read');
-    expect(findOp(ops, 'agency_rich_clarify').auth).toBe('read');
-    expect(findOp(ops, 'agency_suppress_warning').auth).toBe('write');
-    expect(findOp(ops, 'agency_unsuppress_warning').auth).toBe('write');
-    expect(findOp(ops, 'agency_dismiss_pattern').auth).toBe('write');
-    expect(findOp(ops, 'agency_notifications').auth).toBe('read');
-    expect(findOp(ops, 'agency_full_status').auth).toBe('read');
-  });
-
   describe('agency_enable', () => {
     it('enables with default project path', async () => {
       const status = { enabled: true, watching: true };

package/src/runtime/facades/archive-facade.test.ts

@@ -82,49 +82,6 @@ describe('archive-facade', () => {
     ops = captureOps(createArchiveFacadeOps(runtime));
   });
 
-  // ─── Registration ─────────────────────────────────────────────────
-
-  it('registers 12 ops', () => {
-    expect(ops.size).toBe(12);
-  });
-
-  it('includes all expected op names', () => {
-    const expected = [
-      'vault_archive',
-      'vault_restore',
-      'vault_optimize',
-      'vault_backup',
-      'vault_age_report',
-      'vault_set_temporal',
-      'vault_find_expiring',
-      'vault_find_expired',
-      'knowledge_audit',
-      'knowledge_health',
-      'knowledge_merge',
-      'knowledge_reorganize',
-    ];
-    for (const name of expected) {
-      expect(ops.has(name), `missing op: ${name}`).toBe(true);
-    }
-  });
-
-  // ─── Auth levels ─────────────────────────────────────────────────
-
-  it('has correct auth levels', () => {
-    expect(ops.get('vault_archive')!.auth).toBe('write');
-    expect(ops.get('vault_restore')!.auth).toBe('write');
-    expect(ops.get('vault_optimize')!.auth).toBe('write');
-    expect(ops.get('vault_backup')!.auth).toBe('read');
-    expect(ops.get('vault_age_report')!.auth).toBe('read');
-    expect(ops.get('vault_set_temporal')!.auth).toBe('write');
-    expect(ops.get('vault_find_expiring')!.auth).toBe('read');
-    expect(ops.get('vault_find_expired')!.auth).toBe('read');
-    expect(ops.get('knowledge_audit')!.auth).toBe('read');
-    expect(ops.get('knowledge_health')!.auth).toBe('read');
-    expect(ops.get('knowledge_merge')!.auth).toBe('write');
-    expect(ops.get('knowledge_reorganize')!.auth).toBe('write');
-  });
-
   // ─── vault_archive ──────────────────────────────────────────────
 
   describe('vault_archive', () => {

package/src/runtime/facades/brain-facade.test.ts

@@ -117,98 +117,6 @@ describe('brain-facade', () => {
     ops = captureOps(createBrainFacadeOps(runtime));
   });
 
-  // ─── Registration ─────────────────────────────────────────────────
-
-  it('registers all 30 ops', () => {
-    expect(ops.size).toBe(30);
-  });
-
-  it('includes all expected op names', () => {
-    const expected = [
-      'record_feedback',
-      'brain_feedback',
-      'brain_feedback_stats',
-      'rebuild_vocabulary',
-      'brain_stats',
-      'brain_decay_report',
-      'llm_status',
-      'brain_session_context',
-      'brain_strengths',
-      'brain_global_patterns',
-      'brain_recommend',
-      'brain_build_intelligence',
-      'brain_export',
-      'brain_import',
-      'brain_extract_knowledge',
-      'brain_archive_sessions',
-      'brain_promote_proposals',
-      'brain_lifecycle',
-      'session_list',
-      'session_get',
-      'session_quality',
-      'session_replay',
-      'brain_reset_extracted',
-      'radar_analyze',
-      'radar_candidates',
-      'radar_approve',
-      'radar_dismiss',
-      'radar_flush',
-      'radar_stats',
-      'synthesize',
-    ];
-    for (const name of expected) {
-      expect(ops.has(name), `missing op: ${name}`).toBe(true);
-    }
-  });
-
-  // ─── Auth levels ─────────────────────────────────────────────────
-
-  it('has correct auth levels for read ops', () => {
-    const readOps = [
-      'brain_feedback_stats',
-      'brain_stats',
-      'brain_decay_report',
-      'llm_status',
-      'brain_session_context',
-      'brain_strengths',
-      'brain_global_patterns',
-      'brain_recommend',
-      'brain_export',
-      'session_list',
-      'session_get',
-      'session_quality',
-      'session_replay',
-      'radar_candidates',
-      'radar_stats',
-      'synthesize',
-    ];
-    for (const name of readOps) {
-      expect(ops.get(name)!.auth, `${name} should be read`).toBe('read');
-    }
-  });
-
-  it('has correct auth levels for write ops', () => {
-    const writeOps = [
-      'record_feedback',
-      'brain_feedback',
-      'rebuild_vocabulary',
-      'brain_build_intelligence',
-      'brain_import',
-      'brain_extract_knowledge',
-      'brain_archive_sessions',
-      'brain_promote_proposals',
-      'brain_lifecycle',
-      'brain_reset_extracted',
-      'radar_analyze',
-      'radar_approve',
-      'radar_dismiss',
-      'radar_flush',
-    ];
-    for (const name of writeOps) {
-      expect(ops.get(name)!.auth, `${name} should be write`).toBe('write');
-    }
-  });
-
   // ─── record_feedback ───────────────────────────────────────────────
 
   describe('record_feedback', () => {
@@ -290,13 +198,14 @@ describe('brain-facade', () => {
     });
 
     it('accepts all 4 action types', async () => {
-      for (const action of ['accepted', 'dismissed', 'modified', 'failed']) {
-        const result = await executeOp(ops, 'brain_feedback', {
-          query: 'q',
-          entryId: 'e',
-          action,
-        });
-        expect(result.success, `action ${action} should succeed`).toBe(true);
+      const actions = ['accepted', 'dismissed', 'modified', 'failed'];
+      const results = await Promise.all(
+        actions.map((action) =>
+          executeOp(ops, 'brain_feedback', { query: 'q', entryId: 'e', action }),
+        ),
+      );
+      for (const [i, result] of results.entries()) {
+        expect(result.success, `action ${actions[i]} should succeed`).toBe(true);
       }
     });
   });

package/src/runtime/facades/brain-facade.ts

@@ -513,18 +513,35 @@ export function createBrainFacadeOps(runtime: AgentRuntime): OpDefinition[] {
         'then uses LLM to produce a brief, outline, talking points, or post draft. ' +
         'Includes source attribution, coverage score, and knowledge gap detection.',
       auth: 'read',
-      schema: z.object({
-        query: z.string().describe('Topic to synthesize knowledge about'),
-        format: z
-          .enum(['brief', 'outline', 'talking-points', 'post-draft'])
-          .describe('Output format'),
-        maxEntries: z.number().optional().default(10).describe('Max vault entries to consult'),
-        audience: z
-          .enum(['technical', 'executive', 'general'])
-          .optional()
-          .default('general')
-          .describe('Target audience for tone and language'),
-      }),
+      schema: z.preprocess(
+        (val) => {
+          if (val !== null && typeof val === 'object' && !Array.isArray(val)) {
+            const obj = val as Record<string, unknown>;
+            // Accept "topic" as alias for "query"
+            if (obj.topic !== undefined && obj.query === undefined) {
+              return { ...obj, query: obj.topic };
+            }
+          }
+          return val;
+        },
+        z.object({
+          query: z.string().describe('Topic to synthesize knowledge about (alias: topic)'),
+          topic: z.string().optional().describe('Alias for query'),
+          format: z
+            .enum(['brief', 'outline', 'talking-points', 'post-draft'])
+            .optional()
+            .default('brief')
+            .describe(
+              'Output format: brief | outline | talking-points | post-draft (default: "brief")',
+            ),
+          maxEntries: z.number().optional().default(10).describe('Max vault entries to consult'),
+          audience: z
+            .enum(['technical', 'executive', 'general'])
+            .optional()
+            .default('general')
+            .describe('Target audience for tone and language'),
+        }),
+      ),
       handler: async (params) => {
         return knowledgeSynthesizer.synthesize(params.query as string, {
           format: params.format as 'brief' | 'outline' | 'talking-points' | 'post-draft',

package/src/runtime/facades/branching-facade.test.ts

@@ -1,6 +1,5 @@
 /**
  * Colocated contract tests for branching-facade.ts.
- * Verifies the facade wrapper delegates to branching-ops.
  */
 
 import { describe, it, expect, vi } from 'vitest';
@@ -21,23 +20,37 @@ function makeRuntime(): AgentRuntime {
 }
 
 describe('branching-facade', () => {
-  it('returns all 5 branching ops', () => {
-    const ops = createBranchingFacadeOps(makeRuntime());
-    expect(ops).toHaveLength(5);
-    const names = ops.map((o) => o.name);
-    expect(names).toContain('vault_branch');
-    expect(names).toContain('vault_branch_add');
-    expect(names).toContain('vault_branch_list');
-    expect(names).toContain('vault_merge_branch');
-    expect(names).toContain('vault_delete_branch');
+  describe('vault_branch', () => {
+    it('creates branch and returns created: true', async () => {
+      const runtime = makeRuntime();
+      const ops = createBranchingFacadeOps(runtime);
+      const op = ops.find((o) => o.name === 'vault_branch')!;
+      const result = (await op.handler({ name: 'feature-x' })) as {
+        created: boolean;
+        name: string;
+      };
+      expect(result.created).toBe(true);
+      expect(result.name).toBe('feature-x');
+    });
   });
 
-  it('every op has name, handler, and auth', () => {
-    const ops = createBranchingFacadeOps(makeRuntime());
-    for (const op of ops) {
-      expect(typeof op.name).toBe('string');
-      expect(typeof op.handler).toBe('function');
-      expect(typeof op.auth).toBe('string');
-    }
+  describe('vault_branch_list', () => {
+    it('returns empty list when no branches exist', async () => {
+      const runtime = makeRuntime();
+      const ops = createBranchingFacadeOps(runtime);
+      const op = ops.find((o) => o.name === 'vault_branch_list')!;
+      const result = (await op.handler({})) as { branches: unknown[] };
+      expect(result.branches).toEqual([]);
+    });
+  });
+
+  describe('vault_delete_branch', () => {
+    it('returns deleted: true on success', async () => {
+      const runtime = makeRuntime();
+      const ops = createBranchingFacadeOps(runtime);
+      const op = ops.find((o) => o.name === 'vault_delete_branch')!;
+      const result = (await op.handler({ name: 'feature-x' })) as { deleted: boolean };
+      expect(result.deleted).toBe(true);
+    });
   });
 });

package/src/runtime/facades/chat-facade.test.ts

@@ -120,100 +120,9 @@ vi.mock('../../chat/output-compressor.js', () => ({
 describe('createChatFacadeOps', () => {
   const mockRuntime = {} as AgentRuntime;
 
-  it('returns all 41 ops (6 session + 17 transport + 18 service)', () => {
-    const ops = createChatFacadeOps(mockRuntime);
-    expect(ops.length).toBe(41);
-  });
-
-  it('session ops come first', () => {
-    const ops = createChatFacadeOps(mockRuntime);
-    expect(ops[0].name).toBe('chat_session_init');
-    expect(ops[5].name).toBe('chat_session_list');
-  });
-
-  it('transport ops follow session ops', () => {
-    const ops = createChatFacadeOps(mockRuntime);
-    expect(ops[6].name).toBe('chat_chunk_response');
-  });
-
-  it('service ops follow transport ops', () => {
-    const ops = createChatFacadeOps(mockRuntime);
-    // 6 session + 17 transport = index 23 is first service op
-    expect(ops[23].name).toBe('chat_cancel_create');
-  });
-
   it('all op names are unique', () => {
     const ops = createChatFacadeOps(mockRuntime);
     const names = ops.map((o) => o.name);
     expect(new Set(names).size).toBe(names.length);
   });
-
-  it('all ops have valid auth levels', () => {
-    const ops = createChatFacadeOps(mockRuntime);
-    for (const op of ops) {
-      expect(['read', 'write', 'admin']).toContain(op.auth);
-    }
-  });
-
-  it('all ops have async handlers', () => {
-    const ops = createChatFacadeOps(mockRuntime);
-    for (const op of ops) {
-      expect(typeof op.handler).toBe('function');
-    }
-  });
-
-  it('contains all expected op names', () => {
-    const ops = createChatFacadeOps(mockRuntime);
-    const names = new Set(ops.map((o) => o.name));
-    const expectedOps = [
-      // Session ops (6)
-      'chat_session_init',
-      'chat_session_get',
-      'chat_session_append',
-      'chat_session_clear',
-      'chat_session_delete',
-      'chat_session_list',
-      // Transport ops (17)
-      'chat_chunk_response',
-      'chat_auth_init',
-      'chat_auth_check',
-      'chat_auth_authenticate',
-      'chat_auth_revoke',
-      'chat_auth_status',
-      'chat_bridge_init',
-      'chat_bridge_register',
-      'chat_bridge_list',
-      'chat_bridge_execute',
-      'chat_compress_output',
-      'chat_voice_transcribe',
-      'chat_voice_synthesize',
-      'chat_queue_init',
-      'chat_queue_inbox',
-      'chat_queue_reply',
-      'chat_queue_drain',
-      // Service ops (18)
-      'chat_cancel_create',
-      'chat_cancel_stop',
-      'chat_cancel_status',
-      'chat_update_init',
-      'chat_update_request',
-      'chat_update_confirm',
-      'chat_file_detect_intent',
-      'chat_file_build_content',
-      'chat_file_cleanup',
-      'chat_notify_init',
-      'chat_notify_start',
-      'chat_notify_stop',
-      'chat_notify_poll',
-      'chat_notify_status',
-      'chat_browser_init',
-      'chat_browser_acquire',
-      'chat_browser_release',
-      'chat_browser_status',
-    ];
-    for (const name of expectedOps) {
-      expect(names.has(name)).toBe(true);
-    }
-    expect(names.size).toBe(expectedOps.length);
-  });
 });