@soleri/core 9.13.0 → 9.14.0

package/src/index.ts

@@ -608,6 +608,9 @@ export {
 export { loadPersona } from './persona/loader.js';
 export { generatePersonaInstructions, getRandomSignoff } from './persona/prompt-generator.js';
 
+// ─── Schema Helpers ────────────────────────────────────────────────
+export { coerceArray } from './runtime/schema-helpers.js';
+
 // ─── Runtime Factory ────────────────────────────────────────────────
 export { createAgentRuntime } from './runtime/runtime.js';
 export { createSemanticFacades } from './runtime/facades/index.js';
@@ -688,7 +691,12 @@ export {
 } from './packs/index.js';
 export type { PackState, PackTransition } from './packs/index.js';
 export { PackLockfile, inferPackType } from './packs/index.js';
-export { resolvePack, checkNpmVersion, checkVersionCompat } from './packs/index.js';
+export {
+  resolvePack,
+  checkNpmVersion,
+  checkVersionCompat,
+  getBuiltinKnowledgePacksDirs,
+} from './packs/index.js';
 export type {
   PackManifest,
   PackStatus,
@@ -717,7 +725,12 @@ export {
   checkSkillCompatibility,
   ApprovalRequiredError,
 } from './skills/sync-skills.js';
-export type { SkillEntry, SyncResult, ClassifySkillsOptions } from './skills/sync-skills.js';
+export type {
+  SkillEntry,
+  SyncResult,
+  SyncOptions,
+  ClassifySkillsOptions,
+} from './skills/sync-skills.js';
 
 // ─── Plugin System ──────────────────────────────────────────────────────
 export {

package/src/packs/index.ts

@@ -26,5 +26,10 @@ export { PackLifecycleManager } from './pack-lifecycle.js';
 export { PackLockfile, inferPackType, LOCKFILE_VERSION } from './lockfile.js';
 export type { LockEntry, PackType, PackSource, PackTier, LockfileData } from './lockfile.js';
 
-export { resolvePack, checkNpmVersion, checkVersionCompat } from './resolver.js';
+export {
+  resolvePack,
+  checkNpmVersion,
+  checkVersionCompat,
+  getBuiltinKnowledgePacksDirs,
+} from './resolver.js';
 export type { ResolvedPack, ResolveOptions } from './resolver.js';

package/src/packs/resolver.ts

@@ -10,10 +10,33 @@
  */
 
 import { existsSync } from 'node:fs';
-import { resolve, join } from 'node:path';
+import { resolve, join, dirname } from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { mkdirSync, readdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+// ─── Built-in knowledge-packs discovery ──────────────────────────────
+
+const _dirname =
+  typeof __dirname !== 'undefined' ? __dirname : dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Discover the built-in `knowledge-packs/` directory shipped with @soleri/core.
+ * Tries multiple levels up from this file's compiled location to account for
+ * different installation layouts (monorepo dev, npm install, npx).
+ */
+export function getBuiltinKnowledgePacksDirs(): string[] {
+  const dirs: string[] = [];
+  for (let i = 1; i <= 5; i++) {
+    const candidate = resolve(_dirname, ...Array<string>(i).fill('..'), 'knowledge-packs');
+    if (existsSync(candidate)) {
+      dirs.push(candidate);
+      break;
+    }
+  }
+  return dirs;
+}
 
 // ─── Types ────────────────────────────────────────────────────────────
 

package/src/runtime/admin-setup-ops.test.ts

@@ -53,6 +53,8 @@ vi.mock('../skills/sync-skills.js', () => ({
     updated: [],
     skipped: [],
     failed: [],
+    removed: [],
+    cleanedGlobal: [],
   })),
 }));
 

package/src/runtime/admin-setup-ops.ts

@@ -425,7 +425,7 @@ export function createAdminSetupOps(runtime: AgentRuntime): OpDefinition[] {
             const agentName =
               runtime.persona?.name ??
               config.agentId.charAt(0).toUpperCase() + config.agentId.slice(1);
-            skillsResults = syncSkillsToClaudeCode(skillsSourceDirs, agentName);
+            skillsResults = syncSkillsToClaudeCode(skillsSourceDirs, agentName, { global: true });
           } else {
             // Dry run — just discover what would be synced
             const skills = discoverSkills(skillsSourceDirs);

package/src/runtime/capture-ops.ts

@@ -8,6 +8,7 @@
 import { z } from 'zod';
 import type { OpDefinition } from '../facades/types.js';
 import type { AgentRuntime } from './types.js';
+import { coerceArray } from './schema-helpers.js';
 import { detectScope } from '../vault/scope-detector.js';
 import type { ScopeTier, ScopeDetectionResult } from '../vault/scope-detector.js';
 import { syncEntryToMarkdown } from '../vault/vault-markdown-sync.js';
@@ -35,7 +36,7 @@ export function createCaptureOps(runtime: AgentRuntime): OpDefinition[] {
           .enum(['agent', 'project', 'team'])
           .optional()
           .describe('Manual tier override. If omitted, tier is auto-detected from content.'),
-        entries: z.array(
+        entries: coerceArray(
           z.object({
             id: z.string().optional(),
             type: z

package/src/runtime/intake-ops.ts

@@ -9,6 +9,7 @@ import { z } from 'zod';
 import type { OpDefinition } from '../facades/types.js';
 import type { IntakePipeline } from '../intake/intake-pipeline.js';
 import type { TextIngester, IngestSource } from '../intake/text-ingester.js';
+import { coerceArray } from './schema-helpers.js';
 
 /**
  * Create the 7 intake operations.
@@ -191,9 +192,9 @@ export function createIntakeOps(
         'Ingest multiple text items in one call. Each item has its own source metadata. Processed sequentially.',
       auth: 'write',
       schema: z.object({
-        items: z
-          .array(
-            z.object({
+        items: coerceArray(
+          z
+            .object({
               text: z.string(),
               title: z.string(),
               sourceType: z.enum(['article', 'transcript', 'notes', 'documentation']).optional(),
@@ -201,10 +202,9 @@ export function createIntakeOps(
               author: z.string().optional(),
               domain: z.string().optional(),
               tags: z.array(z.string()).optional(),
-            }),
-          )
-          .min(1)
-          .describe('Array of items to ingest'),
+            })
+            .strict(),
+        ).describe('Array of items to ingest (at least 1)'),
       }),
       handler: async (params) => {
         if (!textIngester) return { error: 'Text ingester not configured (LLM client required)' };

package/src/runtime/orchestrate-ops.ts

@@ -136,12 +136,32 @@ export function applyWorkflowOverride(plan: OrchestrationPlan, override: Workflo
     }
   }
 
+  // Inject workflow prompt.md content if available
+  if (override.prompt) {
+    plan.workflowPrompt = override.prompt;
+    plan.workflowName = override.name;
+  }
+
   // Add workflow info to warnings for visibility
   plan.warnings.push(
     `Workflow override "${override.name}" applied (${override.gates.length} gate(s), ${override.tools.length} tool(s)).`,
   );
 }
 
+// ---------------------------------------------------------------------------
+// Workflow prompt preamble helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Prepend workflow prompt content to a task prompt when available.
+ * Returns the original prompt unchanged if no workflow prompt is set.
+ */
+function withWorkflowPreamble(taskPrompt: string, plan: OrchestrationPlan | undefined): string {
+  if (!plan?.workflowPrompt) return taskPrompt;
+  const header = plan.workflowName ? `## Workflow: ${plan.workflowName}` : '## Workflow';
+  return `${header}\n${plan.workflowPrompt}\n\n## Task\n${taskPrompt}`;
+}
+
 // ---------------------------------------------------------------------------
 // In-memory plan store
 // ---------------------------------------------------------------------------
@@ -532,7 +552,7 @@ export function createOrchestrateOps(
           const tasks =
             entry?.plan.steps.map((s) => ({
               taskId: s.id,
-              prompt: s.name,
+              prompt: withWorkflowPreamble(s.name, entry?.plan),
               workspace: process.cwd(),
               runtime: runtimeType,
               timeout: 300_000,
@@ -610,7 +630,8 @@ export function createOrchestrateOps(
         if (runtimeType && runtime.adapterRegistry) {
           const adapter = runtime.adapterRegistry.get(runtimeType);
           const entry = planStore.get(planId);
-          const prompt = entry?.plan.summary ?? `Execute plan ${planId}`;
+          const rawPrompt = entry?.plan.summary ?? `Execute plan ${planId}`;
+          const prompt = withWorkflowPreamble(rawPrompt, entry?.plan);
 
           const adapterResult = await adapter.execute({
             runId: `${planId}-${Date.now()}`,
@@ -692,6 +713,11 @@ export function createOrchestrateOps(
           const healthStatus = contextHealth.check();
           const healthWarning = buildHealthWarning(healthStatus, vault);
 
+          // Build workflow preamble for the calling agent's context
+          const workflowPreamble = entry.plan.workflowPrompt
+            ? withWorkflowPreamble(entry.plan.summary, entry.plan)
+            : undefined;
+
           return {
             plan: { id: planId, status: 'executing' },
             session,
@@ -702,6 +728,7 @@ export function createOrchestrateOps(
               toolsCalled: executionResult.toolsCalled,
               durationMs: executionResult.durationMs,
             },
+            ...(workflowPreamble ? { workflowPreamble } : {}),
             ...(healthWarning ? { contextHealth: healthWarning } : {}),
           };
         }

package/src/runtime/planning-extra-ops.ts

@@ -13,6 +13,7 @@ import fs from 'node:fs';
 import { z } from 'zod';
 import type { OpDefinition } from '../facades/types.js';
 import type { AgentRuntime } from './types.js';
+import { coerceArray } from './schema-helpers.js';
 import type { DriftItem, TaskEvidence } from '../planning/planner.js';
 import type { PlanRunManifest } from '../flows/types.js';
 import { getPlanRunDir } from '../flows/executor.js';
@@ -64,25 +65,24 @@ export function createPlanningExtraOps(runtime: AgentRuntime): OpDefinition[] {
           )
           .optional()
           .describe('Rejected alternative approaches (replaces existing)'),
-        addTasks: z
-          .array(
-            z.object({
-              title: z.string(),
-              description: z.string(),
-              phase: z
-                .string()
-                .optional()
-                .describe('Phase this task belongs to (e.g., "wave-1", "discovery")'),
-              milestone: z
-                .string()
-                .optional()
-                .describe('Milestone this task contributes to (e.g., "v1.0", "mvp")'),
-              parentTaskId: z.string().optional().describe('Parent task ID for sub-task hierarchy'),
-            }),
-          )
+        addTasks: coerceArray(
+          z.object({
+            title: z.string(),
+            description: z.string(),
+            phase: z
+              .string()
+              .optional()
+              .describe('Phase this task belongs to (e.g., "wave-1", "discovery")'),
+            milestone: z
+              .string()
+              .optional()
+              .describe('Milestone this task contributes to (e.g., "v1.0", "mvp")'),
+            parentTaskId: z.string().optional().describe('Parent task ID for sub-task hierarchy'),
+          }),
+        )
           .optional()
           .describe('Tasks to append'),
-        removeTasks: z.array(z.string()).optional().describe('Task IDs to remove'),
+        removeTasks: coerceArray(z.string()).optional().describe('Task IDs to remove'),
       }),
       handler: async (params) => {
         try {
@@ -116,26 +116,24 @@ export function createPlanningExtraOps(runtime: AgentRuntime): OpDefinition[] {
       auth: 'write',
       schema: z.object({
         planId: z.string().describe('Plan ID to split tasks for'),
-        tasks: z
-          .array(
-            z.object({
-              title: z.string(),
-              description: z.string(),
-              dependsOn: z.array(z.string()).optional().describe('Task IDs this task depends on'),
-              phase: z
-                .string()
-                .optional()
-                .describe(
-                  'Phase this task belongs to (e.g., "wave-1", "discovery", "implementation")',
-                ),
-              milestone: z
-                .string()
-                .optional()
-                .describe('Milestone this task contributes to (e.g., "v1.0", "mvp", "beta")'),
-              parentTaskId: z.string().optional().describe('Parent task ID for sub-task hierarchy'),
-            }),
-          )
-          .describe('New task list with optional dependency references (task-1, task-2, etc.)'),
+        tasks: coerceArray(
+          z.object({
+            title: z.string(),
+            description: z.string(),
+            dependsOn: z.array(z.string()).optional().describe('Task IDs this task depends on'),
+            phase: z
+              .string()
+              .optional()
+              .describe(
+                'Phase this task belongs to (e.g., "wave-1", "discovery", "implementation")',
+              ),
+            milestone: z
+              .string()
+              .optional()
+              .describe('Milestone this task contributes to (e.g., "v1.0", "mvp", "beta")'),
+            parentTaskId: z.string().optional().describe('Parent task ID for sub-task hierarchy'),
+          }),
+        ).describe('New task list with optional dependency references (task-1, task-2, etc.)'),
       }),
       handler: async (params) => {
         try {

package/src/runtime/playbook-ops.ts

@@ -8,6 +8,7 @@
 import { z } from 'zod';
 import type { OpDefinition } from '../facades/types.js';
 import type { AgentRuntime } from './types.js';
+import { coerceArray } from './schema-helpers.js';
 import { parsePlaybookFromEntry, validatePlaybook } from '../vault/playbook.js';
 import {
   matchPlaybooks,
@@ -69,7 +70,7 @@ export function createPlaybookOps(runtime: AgentRuntime): OpDefinition[] {
         title: z.string(),
         domain: z.string(),
         description: z.string(),
-        steps: z.array(
+        steps: coerceArray(
           z.object({
             title: z.string(),
             description: z.string(),

package/src/runtime/schema-helpers.test.ts

@@ -0,0 +1,45 @@
+/**
+ * Colocated unit tests for schema-helpers.ts — coerceArray Zod helper.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod';
+import { coerceArray } from './schema-helpers.js';
+
+describe('coerceArray', () => {
+  const schema = coerceArray(z.string());
+
+  it('passes through a native array unchanged', () => {
+    const result = schema.parse(['a', 'b', 'c']);
+    expect(result).toEqual(['a', 'b', 'c']);
+  });
+
+  it('coerces a JSON-stringified array', () => {
+    const result = schema.parse(JSON.stringify(['x', 'y']));
+    expect(result).toEqual(['x', 'y']);
+  });
+
+  it('rejects invalid JSON strings', () => {
+    expect(() => schema.parse('not-json')).toThrow();
+  });
+
+  it('rejects non-array JSON (object)', () => {
+    expect(() => schema.parse(JSON.stringify({ a: 1 }))).toThrow();
+  });
+
+  it('rejects non-array JSON (number)', () => {
+    expect(() => schema.parse(JSON.stringify(42))).toThrow();
+  });
+
+  it('works with complex item schemas', () => {
+    const complex = coerceArray(z.object({ id: z.string(), value: z.number() }));
+    const items = [{ id: 'a', value: 1 }];
+    expect(complex.parse(JSON.stringify(items))).toEqual(items);
+    expect(complex.parse(items)).toEqual(items);
+  });
+
+  it('still validates item types after coercion', () => {
+    // Array of strings schema should reject array of numbers
+    expect(() => schema.parse(JSON.stringify([1, 2, 3]))).toThrow();
+  });
+});

package/src/runtime/schema-helpers.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+
+/**
+ * Wraps a Zod array schema so it also accepts a JSON-stringified array.
+ * MCP transports sometimes serialize array params as strings.
+ */
+export function coerceArray<T extends z.ZodTypeAny>(itemSchema: T) {
+  return z.preprocess((val) => {
+    if (typeof val === 'string') {
+      try {
+        const parsed = JSON.parse(val);
+        if (Array.isArray(parsed)) return parsed;
+      } catch {
+        /* fall through to let Zod reject */
+      }
+    }
+    return val;
+  }, z.array(itemSchema));
+}

package/src/runtime/sync-ops.ts

@@ -10,6 +10,7 @@
 import { z } from 'zod';
 import type { OpDefinition } from '../facades/types.js';
 import type { AgentRuntime } from './types.js';
+import { coerceArray } from './schema-helpers.js';
 import { GitVaultSync, type GitVaultSyncConfig } from '../vault/git-vault-sync.js';
 import type {
   IntelligenceEntry,
@@ -257,15 +258,13 @@ export function createSyncOps(runtime: AgentRuntime): OpDefinition[] {
         'Import an intelligence pack into the vault with content-hash dedup. Entries with duplicate content are skipped.',
       auth: 'write' as const,
       schema: z.object({
-        bundles: z
-          .array(
-            z.object({
-              domain: z.string(),
-              version: z.string(),
-              entries: z.array(z.record(z.unknown())),
-            }),
-          )
-          .describe('Array of IntelligenceBundle objects to import'),
+        bundles: coerceArray(
+          z.object({
+            domain: z.string(),
+            version: z.string(),
+            entries: z.array(z.record(z.unknown())),
+          }),
+        ).describe('Array of IntelligenceBundle objects to import'),
         tier: z
           .enum(['agent', 'project', 'team'])
           .optional()

package/src/runtime/vault-extra-ops.ts

@@ -13,6 +13,7 @@ import { join, basename } from 'node:path';
 import type { OpDefinition } from '../facades/types.js';
 import type { IntelligenceEntry } from '../intelligence/types.js';
 import type { AgentRuntime } from './types.js';
+import { coerceArray } from './schema-helpers.js';
 
 const entrySchema = z.object({
   id: z.string(),
@@ -115,7 +116,7 @@ export function createVaultExtraOps(runtime: AgentRuntime): OpDefinition[] {
       description: 'Add multiple vault entries at once. Uses upsert — existing IDs are updated.',
       auth: 'write',
       schema: z.object({
-        entries: z.array(entrySchema),
+        entries: coerceArray(entrySchema),
       }),
       handler: async (params) => {
         const entries = params.entries as IntelligenceEntry[];
@@ -128,7 +129,7 @@ export function createVaultExtraOps(runtime: AgentRuntime): OpDefinition[] {
       description: 'Remove multiple vault entries by IDs in a single transaction.',
       auth: 'admin',
       schema: z.object({
-        ids: z.array(z.string()),
+        ids: coerceArray(z.string()),
       }),
       handler: async (params) => {
         const ids = params.ids as string[];
@@ -177,7 +178,7 @@ export function createVaultExtraOps(runtime: AgentRuntime): OpDefinition[] {
         'Import vault entries from a JSON bundle. Uses upsert — existing IDs are updated, new IDs are inserted.',
       auth: 'write',
       schema: z.object({
-        entries: z.array(entrySchema),
+        entries: coerceArray(entrySchema),
       }),
       handler: async (params) => {
         const entries = params.entries as IntelligenceEntry[];
@@ -198,7 +199,7 @@ export function createVaultExtraOps(runtime: AgentRuntime): OpDefinition[] {
         'Seed the vault from intelligence data. Idempotent — safe to call multiple times. Uses upsert.',
       auth: 'write',
       schema: z.object({
-        entries: z.array(entrySchema),
+        entries: coerceArray(entrySchema),
       }),
       handler: async (params) => {
         const entries = params.entries as IntelligenceEntry[];